@privy-io/node 0.1.0-alpha.3 → 0.2.0

package/src/lib/identity-token.ts

@@ -0,0 +1,280 @@
+import { JWTPayload } from 'jose';
+import { User } from '../resources';
+import { PrivyAPIError } from '../error';
+import { EmbeddedWalletLinkedAccount, ExternalWalletLinkedAccount } from './user-utils';
+
+/**
+ * Parses the payload of an identity token (JWT) into a `User` object.
+ * Note that the user object may be incomplete due to the size constraints of the identity token.
+ *
+ * @param payload The payload of the identity token.
+ * @returns The user object parsed from the identity token.
+ * @throws If the payload is invalid.
+ */
+export function parseUserFromIdentityTokenPayload(payload: JWTPayload): User {
+  const customMetadata = parseCustomMetadataClaim(payload);
+
+  return {
+    id: payload.sub as string,
+    created_at: parseInt(payload['cr'] as string),
+    is_guest: payload['guest'] === 't',
+    linked_accounts: parseLinkedAccountsClaim(payload),
+    ...(customMetadata ? { custom_metadata: customMetadata } : {}),
+    has_accepted_terms: false,
+    mfa_methods: [],
+  };
+}
+
+function parseLinkedAccountsClaim(payload: JWTPayload): User['linked_accounts'] {
+  const linkedAccountsClaim = payload['linked_accounts'];
+  if (typeof linkedAccountsClaim !== 'string') {
+    throw new InvalidIdentityTokenError('Unable to parse identity token');
+  }
+  const parsedLinkedAccounts = JSON.parse(linkedAccountsClaim) as unknown;
+  if (!Array.isArray(parsedLinkedAccounts)) {
+    throw new InvalidIdentityTokenError('Unable to parse identity token');
+  }
+
+  return parsedLinkedAccounts
+    .map(mapIdLinkedAccountToUserLinkedAccount)
+    .filter((account) => account !== null);
+}
+
+function mapIdLinkedAccountToUserLinkedAccount(account: any): User['linked_accounts'][number] | null {
+  if (account.type === 'email') {
+    return {
+      type: 'email',
+      address: account.address,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountEmail;
+  }
+  if (account.type === 'phone') {
+    return {
+      type: 'phone',
+      phoneNumber: account.phone_number,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountPhone;
+  }
+
+  // Parses all wallet types
+  if (account.type === 'wallet') {
+    if (account.wallet_client_type === 'privy') {
+      return {
+        type: 'wallet',
+        wallet_client_type: 'privy',
+        wallet_client: 'privy',
+        connector_type: 'embedded',
+        id: account.id,
+        address: account.address,
+        chain_type: account.chain_type,
+        first_verified_at: null,
+        verified_at: account.lv,
+        latest_verified_at: account.lv,
+        // The following fields are not present in the identity token,
+        // but are required. We set them to some safe defaults.
+        chain_id: '',
+        delegated: false,
+        imported: false,
+        public_key: '',
+        wallet_index: 0,
+        recovery_method: account.id ? 'privy-v2' : 'privy',
+      } satisfies EmbeddedWalletLinkedAccount;
+    }
+    return {
+      type: 'wallet',
+      wallet_client: 'unknown',
+      address: account.address,
+      chain_type: account.chain_type,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies ExternalWalletLinkedAccount;
+  }
+  if (account.type === 'smart_wallet') {
+    return {
+      type: 'smart_wallet',
+      address: account.address,
+      smart_wallet_type: account.smart_wallet_type,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountSmartWallet;
+  }
+  if (account.type === 'farcaster') {
+    return {
+      type: 'farcaster',
+      fid: account.fid,
+      username: account.username,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+      owner_address: account.oa,
+    } satisfies User.LinkedAccountFarcaster;
+  }
+  if (account.type === 'google_oauth') {
+    return {
+      type: 'google_oauth',
+      subject: account.subject,
+      email: account.email,
+      name: account.name,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountGoogleOAuth;
+  }
+  if (account.type === 'twitter_oauth') {
+    // We send along three potential URL shapes here based on possible profile picture URLs, all
+    // done to preserve size.
+    //   1. pfp begins with `default`, in which case we use the default profile picture URL structure
+    //   2. pfp does not start with https, in which case we assume the profile picture URL structure
+    //   3. Otherwise, we use the pfp URL as-is
+    let pfp = account.pfp ? account.pfp : null;
+    if (pfp?.startsWith('default')) {
+      pfp = `https://abs.twimg.com/sticky/default_profile_images/${pfp}`;
+    } else if (!pfp?.startsWith('https://')) {
+      pfp = `https://pbs.twimg.com/profile_images/${pfp}`;
+    }
+
+    return {
+      type: 'twitter_oauth',
+      subject: account.subject,
+      username: account.username,
+      name: account.name ? account.name : null,
+      profile_picture_url: pfp,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountTwitterOAuth;
+  }
+  if (account.type === 'discord_oauth') {
+    return {
+      type: 'discord_oauth',
+      subject: account.subject,
+      username: account.username,
+      email: null, // not a part of the identity token
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountDiscordOAuth;
+  }
+  if (account.type === 'github_oauth') {
+    return {
+      type: 'github_oauth',
+      subject: account.subject,
+      username: account.username,
+      email: null, // not a part of the identity token
+      name: null, // not a part of the identity token
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountGitHubOAuth;
+  }
+  if (account.type === 'spotify_oauth') {
+    return {
+      type: 'spotify_oauth',
+      subject: account.subject,
+      email: null, // not a part of the identity token
+      name: null, // not a part of the identity token
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountSpotifyOAuth;
+  }
+  if (account.type === 'instagram_oauth') {
+    return {
+      type: 'instagram_oauth',
+      subject: account.subject,
+      username: account.username,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountInstagramOAuth;
+  }
+  if (account.type === 'tiktok_oauth') {
+    return {
+      type: 'tiktok_oauth',
+      subject: account.subject,
+      username: account.username,
+      name: null, // not a part of the identity token
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountTiktokOAuth;
+  }
+  if (account.type === 'linkedin_oauth') {
+    return {
+      type: 'linkedin_oauth',
+      subject: account.subject,
+      email: account.email,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountLinkedInOAuth;
+  }
+  if (account.type === 'apple_oauth') {
+    return {
+      type: 'apple_oauth',
+      subject: account.subject,
+      email: account.email,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountAppleOAuth;
+  }
+  if (account.type === 'cross_app') {
+    return {
+      type: 'cross_app',
+      subject: account.subject,
+      provider_app_id: account.provider_app_id,
+      embedded_wallets: account.embedded_wallets,
+      smart_wallets: account.smart_wallets,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountCrossApp;
+  }
+  if (account.type === 'custom_auth') {
+    return {
+      type: 'custom_auth',
+      custom_user_id: account.custom_user_id,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountCustomJwt;
+  }
+
+  if (account.type === 'telegram') {
+    return {
+      type: 'telegram',
+      telegram_user_id: account.telegram_user_id,
+      username: account.username,
+      first_verified_at: null,
+      verified_at: account.lv,
+      latest_verified_at: account.lv,
+    } satisfies User.LinkedAccountTelegram;
+  }
+
+  return null;
+}
+
+function parseCustomMetadataClaim(payload: JWTPayload): User['custom_metadata'] {
+  const customMetadataClaim = payload['custom_metadata'];
+  if (customMetadataClaim === undefined) {
+    return undefined;
+  }
+  if (typeof customMetadataClaim !== 'string') {
+    throw new InvalidIdentityTokenError('Unable to parse identity token');
+  }
+  const parsedCustomMetadata = JSON.parse(customMetadataClaim) as unknown;
+  if (!parsedCustomMetadata || typeof parsedCustomMetadata !== 'object') {
+    throw new InvalidIdentityTokenError('Unable to parse identity token');
+  }
+
+  return parsedCustomMetadata as User['custom_metadata'];
+}
+
+export class InvalidIdentityTokenError extends PrivyAPIError {}

package/src/lib/user-utils.ts

@@ -0,0 +1,31 @@
+import type { User } from '../resources/users';
+
+export type LinkedAccount = User['linked_accounts'][number];
+
+// prettier-ignore
+export type ExternalWalletLinkedAccount = Exclude<
+  Extract<LinkedAccount, { type: 'wallet' }>,
+  EmbeddedWalletLinkedAccount
+>;
+
+/**
+ * An embedded wallet linked account is a wallet owned by the user that can be used with the Privy API.
+ */
+export type EmbeddedWalletLinkedAccount = Extract<
+  LinkedAccount,
+  { type: 'wallet'; wallet_client_type: 'privy'; connector_type: 'embedded' }
+>;
+
+/**
+ * Determines if a given linked account is an embedded wallet account.
+ * Embedded wallet accounts are wallets that can be used with the Privy API.
+ *
+ * @param account a linked account
+ * @returns whether the account is an embedded wallet account
+ */
+export const isEmbeddedWalletLinkedAccount = (
+  account: User['linked_accounts'][number],
+): account is EmbeddedWalletLinkedAccount =>
+  account.type === 'wallet' &&
+  account.wallet_client_type === 'privy' &&
+  account.connector_type === 'embedded';

package/src/public-api/PrivyClient.ts

@@ -7,6 +7,7 @@ import { PrivyUsersService } from './services/users';
 import { PrivyUtils } from './services/utils';
 import { JwtExchangeService } from '../lib/jwt-exchange';
 import { VERSION } from '../version';
+import { createPrivyAppJWKS } from '../lib/auth';
 
 type InternalClientOptions = Omit<ClientOptions, 'appID' | 'appSecret' | 'baseUrl'>;
 
@@ -15,6 +16,7 @@ export interface PrivyClientOptions extends InternalClientOptions {
   appSecret: string;
   apiUrl?: string;
   authorizationKeyCacheMaxCapacity?: number;
+  jwtVerificationKey?: string;
 }
 
 const DEFAULT_AUTHORIZATION_KEY_CACHE_MAX_CAPACITY = 1000;
@@ -40,6 +42,7 @@ export class PrivyClient {
     apiUrl,
     authorizationKeyCacheMaxCapacity = DEFAULT_AUTHORIZATION_KEY_CACHE_MAX_CAPACITY,
     defaultHeaders,
+    jwtVerificationKey,
     ...clientOptions
   }: PrivyClientOptions) {
     this.privyApiClient = new PrivyAPI({
@@ -53,6 +56,13 @@ export class PrivyClient {
         'privy-client': `node:${VERSION}`,
       },
     });
+    const appJwks = createPrivyAppJWKS({
+      appId: this.privyApiClient.appID,
+      apiUrl: this.privyApiClient.baseURL,
+      headers: { 'privy-client': `node:${VERSION}` },
+      verificationKeyOverride: jwtVerificationKey,
+    });
+
     this.jwtExchangeService = new JwtExchangeService(
       this.privyApiClient.wallets,
       authorizationKeyCacheMaxCapacity,
@@ -61,8 +71,8 @@ export class PrivyClient {
     this.policiesService = new PrivyPoliciesService(this.privyApiClient, this);
     this.transactionsService = new PrivyTransactionsService(this.privyApiClient);
     this.keyQuorumsService = new PrivyKeyQuorumsService(this.privyApiClient, this);
-    this.usersService = new PrivyUsersService(this.privyApiClient);
-    this.utilsService = new PrivyUtils(this.privyApiClient, this);
+    this.usersService = new PrivyUsersService(this.privyApiClient, appJwks);
+    this.utilsService = new PrivyUtils(this.privyApiClient, this, appJwks);
   }
 
   public wallets(): PrivyWalletsService {

package/src/public-api/services/ethereum.ts

@@ -57,10 +57,6 @@ export class PrivyEthereumService {
       chain_type: 'ethereum',
     });
 
-    if (!response.data) {
-      throw new Error(response.error?.message ?? 'Unexpected response from Privy API');
-    }
-
     return response.data;
   }
 
@@ -100,10 +96,6 @@ export class PrivyEthereumService {
       chain_type: 'ethereum',
     });
 
-    if (!response.data) {
-      throw new Error(response.error?.message ?? 'Unexpected response from Privy API');
-    }
-
     return response.data;
   }
 }

package/src/public-api/services/solana.ts

@@ -75,10 +75,6 @@ export class PrivySolanaService {
       params,
     });
 
-    if (!response.data) {
-      throw new Error(response.error?.message ?? 'Unexpected response from Privy API');
-    }
-
     return response.data;
   }
 }

package/src/public-api/services/users.ts

@@ -1,3 +1,37 @@
-import { Users } from '../../resources';
+import { PrivyAPI } from '../../client';
+import { PrivyAppJWKS, verifyIdentityToken } from '../../lib/auth';
+import { User, Users } from '../../resources';
 
-export class PrivyUsersService extends Users {}
+export class PrivyUsersService extends Users {
+  private appJwks: PrivyAppJWKS;
+  constructor(privyApiClient: PrivyAPI, appJwks: PrivyAppJWKS) {
+    super(privyApiClient);
+    this.appJwks = appJwks;
+  }
+
+  /**
+   * Gets a user object from the identity token.
+   * This verifies the token and parses the payload into a `User` object.
+   * Note the user object may be incomplete due to the size constraints of the identity token.
+   *
+   * @param input.id_token the identity token to parse.
+   * @returns the user object parsed from the identity token.
+   *
+   * @example
+   * const idToken = req.cookies.get('privy-id-token'); // or however your framework surfaces cookies
+   * const user = await client.users().get({idToken});
+   */
+  public async get({ id_token }: PrivyUsersService.GetInput): Promise<User> {
+    return verifyIdentityToken({
+      identity_token: id_token,
+      app_id: this._client.appID,
+      verification_key: this.appJwks,
+    });
+  }
+}
+
+export namespace PrivyUsersService {
+  export type GetInput = {
+    id_token: string;
+  };
+}

package/src/public-api/services/utils/auth.ts

@@ -1,21 +1,18 @@
-import { createRemoteJWKSet, importSPKI, errors as joseErrors, jwtVerify, JWTVerifyResult } from 'jose';
 import { PrivyAPI } from '../../../client';
-import { PrivyAPIError } from '../../../core/error';
-
-const DEFAULT_JWKS_CACHE_MAX_AGE = 10 * 60 * 1000; // 10 minutes
-
-const JWT_ALGORITHM = 'ES256';
-const JWT_ISSUER = 'privy.io';
+import {
+  PrivyAppJWKS,
+  verifyAuthToken,
+  VerifyAuthTokenResponse,
+  verifyIdentityToken,
+} from '../../../lib/auth';
+import { User } from '../../../resources';
 
 export class PrivyAuthUtils {
-  private remoteJwks: ReturnType<typeof createRemoteJWKSet>;
+  private appJwks: PrivyAppJWKS;
   private privyAppID: string;
 
-  constructor(privyApiClient: PrivyAPI) {
-    this.remoteJwks = createRemoteJWKSet(
-      new URL(`${privyApiClient.baseURL}/v1/apps/${privyApiClient.appID}/jwks.json`),
-      { cacheMaxAge: DEFAULT_JWKS_CACHE_MAX_AGE },
-    );
+  constructor(privyApiClient: PrivyAPI, appJwks: PrivyAppJWKS) {
+    this.appJwks = appJwks;
     this.privyAppID = privyApiClient.appID;
   }
 
@@ -23,83 +20,22 @@ export class PrivyAuthUtils {
    * Verifies the authentication token, and returns the payload if it is valid.
    *
    * @param authToken - The authentication token to verify.
-   * @param verificationKeyOverride - The verification key to use instead of calling the JWKS endpoint.
    * @returns The payload of the token if it is valid.
    * @throws If the token is invalid.
    */
-  public async verifyAuthToken(
-    authToken: string,
-    verificationKeyOverride?: string,
-  ): Promise<PrivyUsersService.VerifyAuthTokenResponse> {
-    // Because of a type difference, the calls cannot be merged into one.
-    let verifiedToken: JWTVerifyResult;
-    if (verificationKeyOverride !== undefined) {
-      const verificationKey = await importSPKI(verificationKeyOverride, JWT_ALGORITHM);
-      verifiedToken = await jwtVerify(authToken, verificationKey, {
-        typ: 'JWT',
-        algorithms: [JWT_ALGORITHM],
-        issuer: JWT_ISSUER,
-        audience: this.privyAppID,
-      }).catch(mapAndThrowJoseErrors);
-    } else {
-      verifiedToken = await jwtVerify(authToken, this.remoteJwks, {
-        typ: 'JWT',
-        algorithms: [JWT_ALGORITHM],
-        issuer: JWT_ISSUER,
-        audience: this.privyAppID,
-      }).catch(mapAndThrowJoseErrors);
-    }
-
-    return {
-      appId: throwIfNotString(verifiedToken.payload.aud),
-      issuer: throwIfNotString(verifiedToken.payload.iss),
-      issuedAt: throwIfNotNumber(verifiedToken.payload.iat),
-      expiration: throwIfNotNumber(verifiedToken.payload.exp),
-      sessionId: throwIfNotString(verifiedToken.payload['sid']),
-      userId: throwIfNotString(verifiedToken.payload.sub),
-    };
+  public async verifyAuthToken(authToken: string): Promise<VerifyAuthTokenResponse> {
+    return verifyAuthToken({
+      auth_token: authToken,
+      app_id: this.privyAppID,
+      verification_key: this.appJwks,
+    });
   }
-}
-
-export namespace PrivyUsersService {
-  export type VerifyAuthTokenResponse = {
-    appId: string;
-    issuer: string;
-    issuedAt: number;
-    expiration: number;
-    sessionId: string;
-    userId: string;
-  };
-}
-
-export class InvalidAuthTokenError extends PrivyAPIError {}
-
-/** Used for asserting the values in the token payload are strings. */
-function throwIfNotString(value: unknown): string {
-  if (!value || typeof value !== 'string') {
-    throw new InvalidAuthTokenError("Token's payload is invalid");
-  }
-  return value;
-}
-
-/** Used for asserting the values in the token payload are numbers. */
-function throwIfNotNumber(value: unknown): number {
-  if (!value || typeof value !== 'number') {
-    throw new InvalidAuthTokenError("Token's payload is invalid");
-  }
-  return value;
-}
 
-/**
- * Used to catch errors thrown by async `jose` functions and map to our own error types.
- * This method will **always** throw an error, so it's return type is `never`.
- */
-function mapAndThrowJoseErrors(error: unknown): never {
-  if (error instanceof joseErrors.JWTExpired) {
-    throw new InvalidAuthTokenError('Authentication token expired');
-  } else if (error instanceof joseErrors.JWTClaimValidationFailed || error instanceof joseErrors.JWTInvalid) {
-    throw new InvalidAuthTokenError('Authentication token is invalid');
-  } else {
-    throw new InvalidAuthTokenError('Failed to verify authentication token');
+  public async verifyIdentityToken(identityToken: string): Promise<User> {
+    return verifyIdentityToken({
+      identity_token: identityToken,
+      app_id: this.privyAppID,
+      verification_key: this.appJwks,
+    });
   }
 }

package/src/public-api/services/utils.ts

@@ -1,3 +1,4 @@
+import { PrivyAppJWKS } from '../../lib/auth';
 import { PrivyAPI } from '../../client';
 import { PrivyClient } from '../PrivyClient';
 import { PrivyAuthUtils } from './utils/auth';
@@ -9,10 +10,10 @@ export class PrivyUtils {
   private _requestFormatter: PrivyRequestFormatter;
   private _auth: PrivyAuthUtils;
 
-  constructor(privyApiClient: PrivyAPI, privyClient: PrivyClient) {
+  constructor(privyApiClient: PrivyAPI, privyClient: PrivyClient, appJwks: PrivyAppJWKS) {
     this._requestSigner = new PrivyRequestSigner(privyClient);
     this._requestFormatter = new PrivyRequestFormatter();
-    this._auth = new PrivyAuthUtils(privyApiClient);
+    this._auth = new PrivyAuthUtils(privyApiClient, appJwks);
   }
 
   public requestSigner(): PrivyRequestSigner {

package/src/resources/policies.ts

@@ -290,7 +290,8 @@ export interface Policy {
 
 export namespace Policy {
   /**
-   * The rules that apply to each method the policy covers.
+   * A rule that defines the conditions and action to take if the conditions are
+   * true.
    */
   export interface Rule {
     id: string;

package/src/resources/users.ts

@@ -63,10 +63,10 @@ export class Users extends APIResource {
    *
    * @example
    * ```ts
-   * const user = await client.users.get('user_id');
+   * const user = await client.users._get('user_id');
    * ```
    */
-  get(userID: string, options?: RequestOptions): APIPromise<User> {
+  _get(userID: string, options?: RequestOptions): APIPromise<User> {
     return this._client.get(path`/v1/users/${userID}`, options);
   }
 
@@ -352,6 +352,7 @@ export interface User {
     | User.LinkedAccountSmartWallet
     | User.LinkedAccountPasskey
     | User.LinkedAccountFarcaster
+    | User.LinkedAccountTelegram
     | User.LinkedAccountEthereum
     | User.LinkedAccountEthereumEmbeddedWallet
     | User.LinkedAccountSolana
@@ -685,6 +686,26 @@ export namespace User {
     username?: string;
   }
 
+  export interface LinkedAccountTelegram {
+    first_verified_at: number | null;
+
+    latest_verified_at: number | null;
+
+    telegram_user_id: string;
+
+    type: 'telegram';
+
+    verified_at: number;
+
+    first_name?: string | null;
+
+    last_name?: string | null;
+
+    photo_url?: string | null;
+
+    username?: string | null;
+  }
+
   export interface LinkedAccountEthereum {
     address: string;
 
@@ -1113,7 +1134,8 @@ export namespace UserCreateParams {
       | 'near'
       | 'spark'
       | 'ton'
-      | 'starknet';
+      | 'starknet'
+      | 'movement';
 
     /**
      * Additional signers for the wallet.
@@ -1210,6 +1232,8 @@ export namespace UserPregenerateWalletsParams {
       | 'cosmos'
       | 'stellar'
       | 'sui'
+      | 'aptos'
+      | 'movement'
       | 'tron'
       | 'bitcoin-segwit'
       | 'near'