@scalekit-sdk/node 1.0.14 → 2.0.1

package/src/scalekit.ts

@@ -9,10 +9,12 @@ import DirectoryClient from './directory';
 import DomainClient from './domain';
 import OrganizationClient from './organization';
 import PasswordlessClient from './passwordless';
+import UserClient from './user';
 import { IdpInitiatedLoginClaims, IdTokenClaim, User } from './types/auth';
-import { AuthenticationOptions, AuthenticationResponse, AuthorizationUrlOptions, GrantType } from './types/scalekit';
+import { AuthenticationOptions, AuthenticationResponse, AuthorizationUrlOptions, GrantType, LogoutUrlOptions, RefreshTokenResponse ,TokenValidationOptions } from './types/scalekit';
 
 const authorizeEndpoint = "oauth/authorize";
+const logoutEndpoint = "oidc/logout";
 const WEBHOOK_TOLERANCE_IN_SECONDS = 5 * 60; // 5 minutes
 const WEBHOOK_SIGNATURE_VERSION = "v1";
 
@@ -33,6 +35,7 @@ export default class ScalekitClient {
   readonly domain: DomainClient;
   readonly directory: DirectoryClient;
   readonly passwordless: PasswordlessClient;
+  readonly user: UserClient;
   constructor(
     envUrl: string,
     clientId: string,
@@ -67,6 +70,10 @@ export default class ScalekitClient {
       this.grpcConnect,
       this.coreClient
     );
+    this.user = new UserClient(
+      this.grpcConnect,
+      this.coreClient
+    );
   }
 
   /**
@@ -83,10 +90,14 @@ export default class ScalekitClient {
    * @param {string} options.provider Provider i.e. google, github, etc.
    * @param {string} options.codeChallenge Code challenge parameter in case of PKCE
    * @param {string} options.codeChallengeMethod Code challenge method parameter in case of PKCE
+   * @param {string} options.prompt Prompt parameter to control the authorization server's authentication behavior
    * 
    * @example
    * const scalekit = new Scalekit(envUrl, clientId, clientSecret);
-   * const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, { scopes: ['openid', 'profile'] });
+   * const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, { 
+   *   scopes: ['openid', 'profile'],
+   *   prompt: 'create'
+   * });
    * @returns {string} authorization url
    */
   getAuthorizationUrl(
@@ -114,7 +125,8 @@ export default class ScalekitClient {
       ...(options.organizationId && { organization_id: options.organizationId }),
       ...(options.codeChallenge && { code_challenge: options.codeChallenge }),
       ...(options.codeChallengeMethod && { code_challenge_method: options.codeChallengeMethod }),
-      ...(options.provider && { provider: options.provider })
+      ...(options.provider && { provider: options.provider }),
+      ...(options.prompt && { prompt: options.prompt })
     })
 
     return `${this.coreClient.envUrl}/${authorizeEndpoint}?${qs}`
@@ -141,7 +153,7 @@ export default class ScalekitClient {
       client_secret: this.coreClient.clientSecret,
       ...(options?.codeVerifier && { code_verifier: options.codeVerifier })
     }))
-    const { id_token, access_token, expires_in } = res.data;
+    const { id_token, access_token, expires_in , refresh_token } = res.data;
     const claims = jose.decodeJwt<IdTokenClaim>(id_token);
     const user = <User>{};
     for (const [k, v] of Object.entries(claims)) {
@@ -154,7 +166,8 @@ export default class ScalekitClient {
       user,
       idToken: id_token,
       accessToken: access_token,
-      expiresIn: expires_in
+      expiresIn: expires_in,
+      refreshToken: refresh_token
     }
   }
 
@@ -162,27 +175,56 @@ export default class ScalekitClient {
   * Get the idp initiated login claims
   * 
   * @param {string} idpInitiatedLoginToken The idp_initiated_login query param from the URL
+  * @param {TokenValidationOptions} options Optional validation options for issuer and audience
   * @returns {object} Returns the idp initiated login claims
   */
-  async getIdpInitiatedLoginClaims(idpInitiatedLoginToken: string): Promise<IdpInitiatedLoginClaims> {
-    return this.validateToken<IdpInitiatedLoginClaims>(idpInitiatedLoginToken);
+  async getIdpInitiatedLoginClaims(idpInitiatedLoginToken: string, options?: TokenValidationOptions): Promise<IdpInitiatedLoginClaims> {
+    return this.validateToken<IdpInitiatedLoginClaims>(idpInitiatedLoginToken, options);
   }
 
   /**
-   * Validates the access token. 
+   * Validates the access token and returns a boolean result.
    * 
    * @param {string} token The token to be validated.
+   * @param {TokenValidationOptions} options Optional validation options for issuer, audience, and scopes
    * @return {Promise<boolean>} Returns true if the token is valid, false otherwise.
    */
-  async validateAccessToken(token: string): Promise<boolean> {
+  async validateAccessToken(token: string, options?: TokenValidationOptions): Promise<boolean> {
     try {
-      await this.validateToken(token);
+      await this.validateToken(token, options);
       return true;
     } catch (_) {
       return false;
     }
   }
 
+
+
+  /**
+   * Returns the logout URL that can be used to log out the user.
+   * @param {LogoutUrlOptions} options Logout URL options
+   * @param {string} options.idTokenHint The ID Token previously issued to the client
+   * @param {string} options.postLogoutRedirectUri URL to redirect after logout
+   * @param {string} options.state Opaque value to maintain state between request and callback
+   * @returns {string} The logout URL
+   * 
+   * @example
+   * const scalekit = new Scalekit(envUrl, clientId, clientSecret);
+   * const logoutUrl = scalekit.getLogoutUrl({
+   *   postLogoutRedirectUri: 'https://example.com',
+   *   state: 'some-state'
+   * });
+   */
+  getLogoutUrl(options?: LogoutUrlOptions): string {
+    const qs = QueryString.stringify({
+      ...(options?.idTokenHint && { id_token_hint: options.idTokenHint }),
+      ...(options?.postLogoutRedirectUri && { post_logout_redirect_uri: options.postLogoutRedirectUri }),
+      ...(options?.state && { state: options.state })
+    });
+
+    return `${this.coreClient.envUrl}/${logoutEndpoint}${qs ? `?${qs}` : ''}`;
+  }
+
   /**
    * Verifies the payload of the webhook
    * 
@@ -217,24 +259,69 @@ export default class ScalekitClient {
   }
 
   /**
-   * Validate token
+   * Validates a token and returns its payload if valid.
+   * Supports issuer, audience, and scope validation.
    * 
    * @param {string} token The token to be validated
-   * @return {Promise<T>} Returns the payload of the token
+   * @param {TokenValidationOptions} options Optional validation options for issuer, audience, and scopes
+   * @return {Promise<T>} Returns the token payload if valid
+   * @throws {Error} If token is invalid or missing required scopes
    */
-  private async validateToken<T>(token: string): Promise<T> {
+  async validateToken<T>(token: string, options?: TokenValidationOptions): Promise<T> {
     await this.coreClient.getJwks();
     const jwks = jose.createLocalJWKSet({
       keys: this.coreClient.keys
     })
     try {
-      const { payload } = await jose.jwtVerify<T>(token, jwks);
+      const { payload } = await jose.jwtVerify<T>(token, jwks, {
+        ...(options?.issuer && { issuer: options.issuer }),
+        ...(options?.audience && { audience: options.audience })
+      });
+      
+      if (options?.requiredScopes && options.requiredScopes.length > 0) {
+        this.verifyScopes(token, options.requiredScopes);
+      }
+
       return payload;
     } catch (_) {
       throw new Error("Invalid token");
     }
   }
 
+  /**
+   * Verify that the token contains the required scopes
+   * 
+   * @param {string} token The token to verify
+   * @param {string[]} requiredScopes The scopes that must be present in the token
+   * @return {boolean} Returns true if all required scopes are present
+   * @throws {Error} If required scopes are missing, with details about which scopes are missing
+   */
+  verifyScopes(token: string, requiredScopes: string[]): boolean {
+    const payload = jose.decodeJwt(token);
+    const scopes = this.extractScopesFromPayload(payload);
+    
+    const missingScopes = requiredScopes.filter(scope => !scopes.includes(scope));
+    
+    if (missingScopes.length > 0) {
+      throw new Error(`Token missing required scopes: ${missingScopes.join(', ')}`);
+    }
+    
+    return true;
+  }
+
+  /**
+   * Extract scopes from token payload
+   * 
+   * @param {any} payload The token payload
+   * @return {string[]} Array of scopes found in the token
+   */
+  private extractScopesFromPayload(payload: Record<string, any>): string[] {
+    const scopes = payload.scopes;
+    return Array.isArray(scopes)
+      ? scopes.filter((scope) => !!scope.trim?.())
+      : [];
+  }
+
   /**
    * Verify the timestamp
    * 
@@ -267,6 +354,48 @@ export default class ScalekitClient {
   private computeSignature(secretBytes: Buffer, data: string): string {
     return crypto.createHmac('sha256', secretBytes).update(data).digest('base64');
   }
-}
 
+  /**
+   * Refresh access token using a refresh token
+   * @param {string} refreshToken The refresh token to use
+   * @returns {Promise<RefreshTokenResponse>} Returns new access token, refresh token and other details
+   * @throws {Error} When authentication fails or response data is invalid
+   */
+  async refreshAccessToken(refreshToken: string): Promise<RefreshTokenResponse> {
+    if (!refreshToken) {
+      throw new Error("Refresh token is required");
+    }
+
+    let res;
+    try {
+      res = await this.coreClient.authenticate(QueryString.stringify({
+        grant_type: GrantType.RefreshToken,
+        client_id: this.coreClient.clientId,
+        client_secret: this.coreClient.clientSecret,
+        refresh_token: refreshToken
+      }));
+    } catch (error) {
+      throw new Error(`Failed to refresh token: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    if (!res || !res.data) {
+      throw new Error("Invalid response from authentication server");
+    }
+
+    const { access_token, refresh_token } = res.data;
+
+    // Validate that all required properties exist
+    if (!access_token) {
+      throw new Error("Missing access_token in authentication response");
+    }
+    if (!refresh_token) {
+      throw new Error("Missing refresh_token in authentication response");
+    }
+
+    return {
+      accessToken: access_token,
+      refreshToken: refresh_token
+    };
+  }
+}
 

package/src/types/auth.ts

@@ -62,6 +62,7 @@ export type TokenResponse = {
   access_token: string;
   id_token: string;
   expires_in: number;
+  refresh_token: string;
 }
 
 export type IdpInitiatedLoginClaims ={

package/src/types/scalekit.ts

@@ -17,15 +17,34 @@ export type AuthorizationUrlOptions = {
   codeChallenge?: string;
   codeChallengeMethod?: string;
   provider?: string;
+  prompt?: string;
 }
 
 export type AuthenticationOptions = {
   codeVerifier?: string;
 }
 
+export type TokenValidationOptions = {
+  issuer?: string;
+  audience?: string[];
+  requiredScopes?: string[];
+}
+
 export type AuthenticationResponse = {
   user: User;
   idToken: string;
   accessToken: string;
   expiresIn: number;
+  refreshToken: string;
+}
+
+export type RefreshTokenResponse = {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface LogoutUrlOptions {
+  idTokenHint?: string;
+  postLogoutRedirectUri?: string;
+  state?: string;
 }

package/src/types/user.ts

@@ -0,0 +1,21 @@
+export interface CreateUserRequest {
+  email: string;
+  externalId?: string;
+  phoneNumber?: string;
+  userProfile?: {
+    firstName?: string;
+    lastName?: string;
+  };
+  metadata?: Record<string, string>;
+  sendActivationEmail?: boolean;
+}
+
+export interface UpdateUserRequest {
+  email?: string;
+  externalId?: string;
+  userProfile?: {
+    firstName?: string;
+    lastName?: string;
+  };
+  metadata?: Record<string, string>;
+}

package/src/user.ts

@@ -0,0 +1,291 @@
+import { Empty, PartialMessage } from '@bufbuild/protobuf';
+import { PromiseClient } from '@connectrpc/connect';
+import GrpcConnect from './connect';
+import CoreClient from './core';
+import { UserService } from './pkg/grpc/scalekit/v1/users/users_connect';
+import { 
+  CreateUserAndMembershipRequest,
+  CreateUserAndMembershipResponse,
+  DeleteUserRequest,
+  GetUserRequest,
+  GetUserResponse,
+  ListUsersRequest,
+  ListUsersResponse,
+  UpdateUserRequest,
+  UpdateUserResponse,
+  User,
+  UpdateUser,
+  CreateUser,
+  CreateUserProfile,
+  CreateMembershipRequest,
+  CreateMembershipResponse,
+  DeleteMembershipRequest,
+  UpdateMembershipRequest,
+  UpdateMembershipResponse,
+  ListOrganizationUsersRequest,
+  ListOrganizationUsersResponse,
+  CreateMembership,
+  UpdateMembership
+} from './pkg/grpc/scalekit/v1/users/users_pb';
+import { CreateUserRequest, UpdateUserRequest as UpdateUserRequestType } from './types/user';
+
+export default class UserClient {
+  private client: PromiseClient<typeof UserService>;
+
+  constructor(
+    private readonly grpcConnect: GrpcConnect,
+    private readonly coreClient: CoreClient
+  ) {
+    this.client = this.grpcConnect.createClient(UserService);
+  }
+
+  /**
+   * Create a new user and add them to an organization
+   * @param {string} organizationId The organization id
+   * @param {CreateUserRequest} options The user creation options
+   * @returns {Promise<CreateUserAndMembershipResponse>} The created user
+   */
+  async createUserAndMembership(organizationId: string, options: CreateUserRequest): Promise<CreateUserAndMembershipResponse> {
+    if (!organizationId) {
+      throw new Error('organizationId is required');
+    }
+    if (!options.email) {
+      throw new Error('email is required');
+    }
+
+    const user = new CreateUser({
+      email: options.email,
+      userProfile: options.userProfile ? new CreateUserProfile({
+        firstName: options.userProfile.firstName,
+        lastName: options.userProfile.lastName
+      }) : undefined,
+      metadata: options.metadata
+    });
+
+    const request: PartialMessage<CreateUserAndMembershipRequest> = {
+      organizationId,
+      user
+    };
+
+    if (options.sendActivationEmail !== undefined) {
+      request.sendActivationEmail = options.sendActivationEmail;
+    }
+
+    const response = await this.coreClient.connectExec(
+      this.client.createUserAndMembership,
+      request
+    );
+    
+    if (!response.user) {
+      throw new Error('Failed to create user');
+    }
+    
+    return response;
+  }
+
+  /**
+   * Get a user by id
+   * @param {string} userId The user id
+   * @returns {Promise<GetUserResponse>} The user
+   */
+  async getUser(userId: string): Promise<GetUserResponse> {
+    return this.coreClient.connectExec(
+      this.client.getUser,
+      {
+        identities: {
+          case: 'id',
+          value: userId
+        }
+      }
+    );
+  }
+
+  /**
+   * List users with pagination
+   * @param {object} options The pagination options
+   * @param {number} options.pageSize The page size
+   * @param {string} options.pageToken The page token
+   * @returns {Promise<ListUsersResponse>} The list of users
+   */
+  async listUsers(options?: {
+    pageSize?: number,
+    pageToken?: string
+  }): Promise<ListUsersResponse> {
+    return this.coreClient.connectExec(
+      this.client.listUsers,
+      {
+        pageSize: options?.pageSize,
+        pageToken: options?.pageToken
+      }
+    );
+  }
+
+  /**
+   * Update a user
+   * @param {string} userId The user id
+   * @param {UpdateUserRequestType} options The update options
+   * @returns {Promise<UpdateUserResponse>} The updated user
+   */
+  async updateUser(userId: string, options: UpdateUserRequestType): Promise<UpdateUserResponse> {
+    const updateUser = new UpdateUser({
+      userProfile: options.userProfile ? {
+        firstName: options.userProfile.firstName,
+        lastName: options.userProfile.lastName
+      } : undefined,
+      metadata: options.metadata
+    });
+
+    return this.coreClient.connectExec(
+      this.client.updateUser,
+      {
+        identities: {
+          case: 'id',
+          value: userId
+        },
+        user: updateUser
+      }
+    );
+  }
+
+  /**
+   * Delete a user
+   * @param {string} userId The user id
+   * @returns {Promise<Empty>} Empty response
+   */
+  async deleteUser(userId: string): Promise<Empty> {
+    return this.coreClient.connectExec(
+      this.client.deleteUser,
+      {
+        identities: {
+          case: 'id',
+          value: userId
+        }
+      }
+    );
+  }
+
+  /**
+   * Create a membership for a user in an organization
+   * @param {string} organizationId The organization id
+   * @param {string} userId The user id
+   * @param {object} options The membership options
+   * @param {string[]} options.roles The roles to assign
+   * @param {Record<string, string>} options.metadata Optional metadata
+   * @param {boolean} options.sendActivationEmail Whether to send activation email
+   * @returns {Promise<CreateMembershipResponse>} The response with updated user
+   */
+  async createMembership(
+    organizationId: string,
+    userId: string,
+    options: {
+      roles?: string[],
+      metadata?: Record<string, string>,
+      sendActivationEmail?: boolean
+    } = {}
+  ): Promise<CreateMembershipResponse> {
+    const membership = new CreateMembership({
+      roles: options.roles?.map(role => ({ name: role })) || [],
+      metadata: options.metadata || {}
+    });
+
+    const request: PartialMessage<CreateMembershipRequest> = {
+      organizationId,
+      identities: {
+        case: 'id',
+        value: userId
+      },
+      membership
+    };
+
+    if (options.sendActivationEmail !== undefined) {
+      request.sendActivationEmail = options.sendActivationEmail;
+    }
+
+    return this.coreClient.connectExec(
+      this.client.createMembership,
+      request
+    );
+  }
+
+  /**
+   * Delete a user's membership from an organization
+   * @param {string} organizationId The organization id
+   * @param {string} userId The user id
+   * @returns {Promise<Empty>} Empty response
+   */
+  async deleteMembership(
+    organizationId: string,
+    userId: string
+  ): Promise<Empty> {
+    return this.coreClient.connectExec(
+      this.client.deleteMembership,
+      {
+        organizationId,
+        identities: {
+          case: 'id',
+          value: userId
+        }
+      }
+    );
+  }
+
+  /**
+   * Update a user's membership in an organization
+   * @param {string} organizationId The organization id
+   * @param {string} userId The user id
+   * @param {object} options The update options
+   * @param {string[]} options.roles The roles to assign
+   * @param {Record<string, string>} options.metadata Optional metadata
+   * @returns {Promise<UpdateMembershipResponse>} The response with updated user
+   */
+  async updateMembership(
+    organizationId: string,
+    userId: string,
+    options: {
+      roles?: string[],
+      metadata?: Record<string, string>
+    } = {}
+  ): Promise<UpdateMembershipResponse> {
+    const membership = new UpdateMembership({
+      roles: options.roles?.map(role => ({ name: role })) || [],
+      metadata: options.metadata || {}
+    });
+
+    return this.coreClient.connectExec(
+      this.client.updateMembership,
+      {
+        organizationId,
+        identities: {
+          case: 'id',
+          value: userId
+        },
+        membership
+      }
+    );
+  }
+
+  /**
+   * List users in an organization with pagination
+   * @param {string} organizationId The organization id
+   * @param {object} options The pagination options
+   * @param {number} options.pageSize The page size
+   * @param {string} options.pageToken The page token
+   * @returns {Promise<ListOrganizationUsersResponse>} The list of users in the organization
+   */
+  async listOrganizationUsers(
+    organizationId: string,
+    options?: {
+      pageSize?: number,
+      pageToken?: string
+    }
+  ): Promise<ListOrganizationUsersResponse> {
+    return this.coreClient.connectExec(
+      this.client.listOrganizationUsers,
+      {
+        organizationId,
+        pageSize: options?.pageSize,
+        pageToken: options?.pageToken
+      }
+    );
+  }
+}