@privy-io/node 0.1.0-alpha.2

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { PrivyAPIError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new PrivyAPIError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new PrivyAPIError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new PrivyAPIError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new PrivyAPIError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new PrivyAPIError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/lib/authorization.ts

@@ -0,0 +1,153 @@
+import { p256 } from '@noble/curves/nist';
+import { sha256 } from '@noble/hashes/sha2';
+import canonicalize from 'canonicalize';
+import { PrivyAPIError } from '../core/error';
+import { importPKCS8PrivateKey } from './cryptography';
+import { PrivyClient } from '../public-api/PrivyClient';
+
+/**
+ * The authorization context should contain:
+ * - Any authorization private keys that must sign the request
+ * - The JWTs for any users that must sign the request
+ * - Any additional signatures you have computed for the request
+ *
+ * The Privy client will accept the authorization context, sign the request given the parameters,
+ * and include all signatures in the privy-authorization-signature header to the API.
+ */
+export interface AuthorizationContext {
+  /**
+   * The private keys to use for authorization.
+   * These should be base64-encoded PKCS8-formatted private keys, with no PEM headers.
+   */
+  authorization_private_keys?: string[];
+  /**
+   * The JWTs for the users that should sign the request authorization.
+   * These should be valid JWTs for the user.
+   */
+  user_jwts?: string[];
+  /**
+   * The signatures that should be used for authorization.
+   * These should be base64-encoded signatures.
+   */
+  signatures?: string[];
+  /**
+   * Sign functions can be used to sign requests directly, by managing the private keys and signing
+   * logic externally.
+   *
+   * Sign functions should perform an ECDSA P-256 signature on the payload received, and return the
+   * base64-encoded signature.
+   */
+  sign_fns?: AuthorizationContext.SignFn[];
+}
+
+export namespace AuthorizationContext {
+  export type SignFn = (payload: Uint8Array) => Promise<string>;
+}
+
+export type WalletApiRequestSignatureInput = {
+  /** Signature version. 1 is currently the only valid version. */
+  version: 1;
+  /** Request method. Signatures are not required on 'GET' requests. */
+  method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** URL for the request. Should not contain a trailing slash. */
+  url: string;
+  /** Request body. */
+  body: any;
+  /** Privy-specific headers. */
+  headers: {
+    'privy-app-id': string;
+    'privy-idempotency-key'?: string;
+  };
+};
+
+/**
+ * Formats the request payload into the expected authorization payload, canconicalizes it,
+ * and encodes the JSON string into bytes.
+ *
+ * @param request The request to be formatted.
+ * @return The raw bytes representing the authorization payload.
+ */
+export function formatRequestForAuthorizationSignature(input: WalletApiRequestSignatureInput): Uint8Array {
+  const body: unknown = input.body;
+  if (typeof body === 'object' && body !== null && Object.keys(body).length === 0) {
+    // This is a special case, where if the body is empty, we want to serialize it
+    // as an empty string.
+    input.body = '';
+  }
+  const serializedInput = canonicalize(input);
+  if (!serializedInput) {
+    throw new PrivyAPIError('Failed to serialize request for authorization signature');
+  }
+  return new TextEncoder().encode(serializedInput);
+}
+
+/**
+ * Generates authorization signatures from the given authorization context and signable request.
+ * This method handles JWT exchange and private key signing.
+ *
+ * Manual signing of requests is intended for advanced use cases.
+ *
+ * @param authorizationContext The authorization context containing JWTs, private keys, and signatures.
+ * @param input The request payload to sign.
+ * @returns An array of authorization signatures.
+ */
+export async function generateAuthorizationSignatures(
+  client: PrivyClient,
+  {
+    authorizationContext,
+    input,
+  }: {
+    authorizationContext: AuthorizationContext;
+    input: WalletApiRequestSignatureInput;
+  },
+): Promise<string[]> {
+  const payload = formatRequestForAuthorizationSignature(input);
+
+  const userJwts = authorizationContext.user_jwts ?? [];
+  let userKeys: string[] = [];
+  if (userJwts.length > 0) {
+    userKeys = await Promise.all(
+      userJwts.map((jwt) => client._jwtExchange().exchangeJwtForAuthorizationKey(jwt)),
+    );
+  }
+
+  /** These are the private keys provided by the caller, either directly or via JWT exchange */
+  const privateKeys = [...(authorizationContext.authorization_private_keys ?? []), ...userKeys];
+
+  /** These are the signatures calculated from the private keys */
+  const calculatedSignatures = privateKeys.map((sk) =>
+    generateAuthorizationSignature({ authorizationPrivateKey: sk, input: payload }),
+  );
+
+  /** These are the signatures calculated externally from the given sign functions */
+  const signFnSignatures = await Promise.all(
+    (authorizationContext.sign_fns ?? []).map((signFn) => signFn(payload)),
+  );
+
+  /** These are the signatures provided directly by the caller */
+  const providedRawSignatures = authorizationContext.signatures ?? [];
+
+  return [...providedRawSignatures, ...calculatedSignatures, ...signFnSignatures];
+}
+
+/**
+ * Signs the given request with the provided private key.
+ *
+ * @param authorizationPrivateKey The base64-encoded PKCS8-formatted private key, with no PEM headers.
+ * @param input The request payload to sign, or one serialized using {@link formatRequestForAuthorizationSignature}.
+ * @return The authorization signature.
+ */
+export function generateAuthorizationSignature({
+  authorizationPrivateKey,
+  input,
+}: {
+  authorizationPrivateKey: string;
+  input: WalletApiRequestSignatureInput | Uint8Array;
+}): string {
+  const payload = input instanceof Uint8Array ? input : formatRequestForAuthorizationSignature(input);
+  const privateKey = importPKCS8PrivateKey(authorizationPrivateKey);
+
+  const signature = p256.sign(sha256(payload), privateKey).toBytes('der');
+  // We fall back to `Buffer` here as Uint8Array.toBase64 is not widely supported yet
+  return Buffer.from(signature).toString('base64');
+}

package/src/lib/cryptography.ts

@@ -0,0 +1,109 @@
+import { Chacha20Poly1305 } from '@hpke/chacha20poly1305';
+import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from '@hpke/core';
+import { p256 } from '@noble/curves/nist';
+import type { PrivKey } from '@noble/curves/utils';
+
+/**
+ * Imports a P-256 private key for use with the `@noble/curves` library.
+ *
+ * @param privateKey - A base64-encoded PKCS8-formatted private key, with no PEM headers.
+ * @returns A private key object for the P-256 curve.
+ * @internal
+ */
+export function importPKCS8PrivateKey(privateKey: string): PrivKey {
+  // We fall back to `Buffer` here as Uint8Array.fromBase64 is not widely supported yet
+  const pkcs8Bytes = Buffer.from(privateKey, 'base64');
+  const privateKeyStart = pkcs8Bytes.indexOf(Buffer.from([0x04, 0x20]));
+
+  if (privateKeyStart === -1) {
+    throw new Error('Invalid wallet authorization private key');
+  }
+  const privateKeyBytes = pkcs8Bytes.subarray(privateKeyStart + 2, privateKeyStart + 34);
+  return p256.Point.Fn.fromBytes(privateKeyBytes);
+}
+
+/** @internal */
+export interface HPKERecipient {
+  /** The recipient's public key. */
+  publicKeySpki: Uint8Array;
+  /**
+   * Decrypts an HPKE-encrypted message received from the sender.
+   * @param encapsulatedKey - The encapsulated key to use for decryption.
+   * @param ciphertext - The ciphertext to decrypt.
+   * @returns The decrypted message.
+   */
+  decryptPayload: (encapsulatedKey: Uint8Array, ciphertext: Uint8Array) => Promise<Uint8Array>;
+}
+
+/**
+ * Sets up HPKE for securely requesting a payload (as the recipient)
+ * from a sender (e.g. the Privy API).
+ * @returns The HPKE receiver object.
+ * @internal
+ */
+export async function setupHPKERecipient(): Promise<HPKERecipient> {
+  const suite = new CipherSuite({
+    kem: new DhkemP256HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Chacha20Poly1305(),
+  });
+
+  const keypair = await suite.kem.generateKeyPair();
+  const publicKeySpki = await crypto.subtle.exportKey('spki', keypair.publicKey);
+
+  return {
+    publicKeySpki: new Uint8Array(publicKeySpki),
+    decryptPayload: async (encapsulatedKey: Uint8Array, ciphertext: Uint8Array) => {
+      const recipient = await suite.createRecipientContext({
+        recipientKey: keypair.privateKey,
+        enc: encapsulatedKey,
+      });
+
+      const decodedBytes = await recipient.open(ciphertext);
+
+      return new Uint8Array(decodedBytes);
+    },
+  };
+}
+
+/** @internal */
+export interface HPKESender {
+  /**
+   * Encrypts a payload for the recipient in an HPKE flow.
+   * @param publicKey - The public key of the recipient to use for encryption.
+   * @param payload - The payload to encrypt.
+   * @returns The encapsulated key and ciphertext to send out.
+   */
+  encryptPayload: (publicKey: Uint8Array, payload: Uint8Array) => Promise<HPKESender.EncryptPayloadOutput>;
+}
+
+export namespace HPKESender {
+  export interface EncryptPayloadOutput {
+    ciphertext: Uint8Array;
+    encapsulatedKey: Uint8Array;
+  }
+}
+
+export async function setupHPKESender(): Promise<HPKESender> {
+  const suite = new CipherSuite({
+    kem: new DhkemP256HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Chacha20Poly1305(),
+  });
+
+  return {
+    encryptPayload: async (publicKey: Uint8Array, payload: Uint8Array) => {
+      const recipientPublicKey = await suite.kem.deserializePublicKey(publicKey);
+      const sender = await suite.createSenderContext({
+        recipientPublicKey,
+      });
+
+      const ciphertext = await sender.seal(payload);
+
+      return {
+        ciphertext: new Uint8Array(ciphertext),
+        encapsulatedKey: new Uint8Array(sender.enc),
+      };
+    },
+  };
+}

package/src/lib/jwt-exchange.ts

@@ -0,0 +1,65 @@
+import { LRUCache } from 'lru-cache';
+import { PrivyAPIError } from '../core/error';
+import { Wallets } from '../resources';
+import { HPKERecipient, setupHPKERecipient } from './cryptography';
+
+export class JwtExchangeService {
+  private _hpkeRecipient: HPKERecipient | null = null;
+  private walletsService: Wallets;
+  private jwtCache: LRUCache<string, string>;
+
+  constructor(walletsService: Wallets, authorizationKeyCacheMaxCapacity: number) {
+    this.walletsService = walletsService;
+    this.jwtCache = new LRUCache({ max: authorizationKeyCacheMaxCapacity });
+  }
+
+  private async getHpkeRecipient(): Promise<HPKERecipient> {
+    if (!this._hpkeRecipient) {
+      this._hpkeRecipient = await setupHPKERecipient();
+    }
+    return this._hpkeRecipient;
+  }
+
+  /**
+   * Exchanges a JWT for an authorization key.
+   * @param jwt - The JWT to exchange for an authorization key.
+   * @returns The (base-64 encoded PKCS8-formatted) authorization key.
+   * @internal
+   */
+  async exchangeJwtForAuthorizationKey(jwt: string): Promise<string> {
+    const cachedAuthorizationKey = this.jwtCache.get(jwt);
+    if (cachedAuthorizationKey) {
+      return cachedAuthorizationKey;
+    }
+
+    const { publicKeySpki, decryptPayload } = await this.getHpkeRecipient();
+
+    const signer = await this.walletsService.authenticateWithJwt({
+      user_jwt: jwt,
+      encryption_type: 'HPKE',
+      // We fall back to `Buffer` here as Uint8Array.toBase64 is not widely supported yet
+      recipient_public_key: Buffer.from(publicKeySpki).toString('base64'),
+    });
+    if (
+      'encrypted_authorization_key' in signer &&
+      signer.encrypted_authorization_key.encryption_type === 'HPKE'
+    ) {
+      const encryptedAuthorizationKey = signer.encrypted_authorization_key;
+      const decryptedAuthorizationKey = await decryptPayload(
+        // We fall back to `Buffer` here as Uint8Array.fromBase64 is not widely supported yet
+        Buffer.from(encryptedAuthorizationKey.encapsulated_key, 'base64'),
+        Buffer.from(encryptedAuthorizationKey.ciphertext, 'base64'),
+      );
+      const authorizationKey = new TextDecoder().decode(decryptedAuthorizationKey);
+      this.jwtCache.set(
+        jwt,
+        authorizationKey,
+        // Setting the TTL here makes the LRU cache check and prune on `.get`.
+        { ttl: signer.expires_at - Date.now() },
+      );
+      return authorizationKey;
+    } else {
+      throw new PrivyAPIError('JWT exchange failed: unsupported encryption type');
+    }
+  }
+}

package/src/lib/wallet-entropy.ts

@@ -0,0 +1,48 @@
+import { base58 } from '@scure/base';
+import { PrivyAPIError } from '../error';
+
+export interface EntropyToBytesInput {
+  entropy: string | Uint8Array;
+  entropyType: 'hd' | 'private-key';
+  chainType: 'ethereum' | 'solana';
+}
+
+export function entropyToBytes(wallet: EntropyToBytesInput): Uint8Array {
+  const { entropy, entropyType, chainType } = wallet;
+  if (typeof entropy !== 'string') {
+    // If a straight entropy byte array is provided, return it
+    return entropy;
+  }
+
+  switch (entropyType) {
+    case 'hd':
+      // HD entropy is a BIP39 mnemonic that can be encoded as utf-8
+      return new TextEncoder().encode(entropy);
+    case 'private-key':
+      if (chainType === 'ethereum') {
+        try {
+          // Private key strings are hex encoded for Ethereum
+          const entropyWithout0x = entropy.startsWith('0x') ? entropy.slice(2) : entropy;
+          // We fall back to `Buffer` here as Uint8Array.fromHex is not widely supported yet
+          return new Uint8Array(Buffer.from(entropyWithout0x, 'hex'));
+        } catch (error) {
+          throw new PrivyAPIError(`Invalid private key: Ethereum entropy must be hex encoded`);
+        }
+      }
+
+      if (chainType === 'solana') {
+        try {
+          // Private key strings are base58 encoded for Solana
+          return base58.decode(entropy);
+        } catch (error) {
+          throw new PrivyAPIError(`Invalid private key: Solana entropy must be base58 encoded`);
+        }
+      }
+
+      // This should be unreachable, so we check with `satisfies never`
+      throw new PrivyAPIError(`Invalid chain type for imports: ${chainType satisfies never}`);
+    default:
+      // This should be unreachable, so we check with `satisfies never`
+      throw new PrivyAPIError(`Invalid entropy type: ${entropyType satisfies never}`);
+  }
+}

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/public-api/PrivyClient.ts

@@ -0,0 +1,91 @@
+import { ClientOptions, PrivyAPI } from '../client';
+import { PrivyWalletsService } from './services/wallets';
+import { PrivyPoliciesService } from './services/policies';
+import { PrivyTransactionsService } from './services/transactions';
+import { PrivyKeyQuorumsService } from './services/key-quorums';
+import { PrivyUsersService } from './services/users';
+import { PrivyUtils } from './services/utils';
+import { JwtExchangeService } from '../lib/jwt-exchange';
+import { VERSION } from '../version';
+
+type InternalClientOptions = Omit<ClientOptions, 'appID' | 'appSecret' | 'baseUrl'>;
+
+export interface PrivyClientOptions extends InternalClientOptions {
+  appId: string;
+  appSecret: string;
+  apiUrl?: string;
+  authorizationKeyCacheMaxCapacity?: number;
+}
+
+const DEFAULT_AUTHORIZATION_KEY_CACHE_MAX_CAPACITY = 1000;
+
+export class PrivyClient {
+  private privyApiClient: PrivyAPI;
+  private walletsService: PrivyWalletsService;
+  private policiesService: PrivyPoliciesService;
+  private transactionsService: PrivyTransactionsService;
+  private keyQuorumsService: PrivyKeyQuorumsService;
+  private usersService: PrivyUsersService;
+  private utilsService: PrivyUtils;
+  private jwtExchangeService: JwtExchangeService;
+
+  /** @internal */
+  _jwtExchange(): JwtExchangeService {
+    return this.jwtExchangeService;
+  }
+
+  public constructor({
+    appId,
+    appSecret,
+    apiUrl,
+    authorizationKeyCacheMaxCapacity = DEFAULT_AUTHORIZATION_KEY_CACHE_MAX_CAPACITY,
+    defaultHeaders,
+    ...clientOptions
+  }: PrivyClientOptions) {
+    this.privyApiClient = new PrivyAPI({
+      ...clientOptions,
+      appID: appId,
+      appSecret: appSecret,
+      baseURL: apiUrl,
+      defaultHeaders: {
+        ...defaultHeaders,
+        // Convention is: <client_name>:<semantic_version>
+        'privy-client': `node:${VERSION}`,
+      },
+    });
+    this.jwtExchangeService = new JwtExchangeService(
+      this.privyApiClient.wallets,
+      authorizationKeyCacheMaxCapacity,
+    );
+    this.walletsService = new PrivyWalletsService(this.privyApiClient, this);
+    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);
+  }
+
+  public wallets(): PrivyWalletsService {
+    return this.walletsService;
+  }
+
+  public policies(): PrivyPoliciesService {
+    return this.policiesService;
+  }
+
+  public transactions(): PrivyTransactionsService {
+    return this.transactionsService;
+  }
+
+  public keyQuorums(): PrivyKeyQuorumsService {
+    return this.keyQuorumsService;
+  }
+
+  public users(): PrivyUsersService {
+    return this.usersService;
+  }
+
+  public utils(): PrivyUtils {
+    return this.utilsService;
+  }
+}