@cubist-labs/cubesigner-sdk 0.4.239 → 0.4.244

package/src/client/api_client.ts

@@ -69,6 +69,7 @@ import type {
   ListBucketsResponse,
   UpdateBucketRequest,
   PolicyInfo,
+  JsonRpcRequest,
 } from "../schema_types";
 import { encodeToBase64 } from "../util";
 import { auditLogEntrySchema } from "../audit_log";
@@ -160,13 +161,19 @@ import {
   type BucketInfo,
 } from "../index";
 import { assertOk, op, type Op, type Operation, apiFetch } from "../fetch";
-import { BaseClient, type ClientConfig, signerSessionFromSessionInfo } from "./base_client";
+import {
+  authHeader,
+  BaseClient,
+  type ClientConfig,
+  signerSessionFromSessionInfo,
+} from "./base_client";
 import { retryOn5XX } from "../retry";
 import { PasskeyLoginChallenge } from "../passkey";
 
 // these types are used in doc comments only
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { RoleAttestationClaims, KeyAttestationClaims } from "../schema_types";
+import { mergeHeaders } from "openapi-fetch";
 
 /**
  * String returned by API when a user does not have an email address (for backwards compatibility)
@@ -217,10 +224,7 @@ export class ApiClient extends BaseClient {
     return new ApiClient(this.sessionMeta, this.sessionManager, this.orgId, {
       ...this.config,
       ...cfg,
-      headers: {
-        ...(this.config.headers ?? {}),
-        ...(cfg.headers ?? {}),
-      },
+      headers: mergeHeaders(this.config.headers, cfg.headers),
     });
   }
 
@@ -258,12 +262,14 @@ export class ApiClient extends BaseClient {
    * @param env The environment to use
    * @param orgId The org to login to
    * @param email The email to send the signature to
+   * @param headers Optional headers to set
    * @returns The partial OIDC token that must be combined with the signature in the email
    */
   static async initEmailOtpAuth(
     env: EnvInterface,
     orgId: string,
     email: string,
+    headers?: HeadersInit,
   ): Promise<EmailOtpResponse> {
     const o = op("/v0/org/{org_id}/oidc/email-otp", "post");
 
@@ -272,6 +278,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body: { email },
+        headers,
       }),
     ).then(assertOk);
   }
@@ -2901,6 +2908,33 @@ export class ApiClient extends BaseClient {
 
   // #endregion
 
+  // #region RPC
+
+  /**
+   * Send a JSON RPC request to the high-level API endpoint.
+   *
+   * @param body JSON RPC request body
+   * @param mfaReceipt Optional MFA receipts
+   * @returns Corresponding response
+   */
+  async rpc(
+    body: JsonRpcRequest,
+    mfaReceipt?: MfaReceipts,
+  ): Promise<CubeSignerResponse<schemas["JsonRpcResponse"]>> {
+    const o = op("/v0/org/{org_id}/rpc", "post");
+    const reqFn = (headers?: HeadersInit) =>
+      this.exec(o, {
+        headers,
+        body: {
+          jsonrpc: "2.0",
+          ...body,
+        },
+      });
+    return await CubeSignerResponse.create(this.env, reqFn, mfaReceipt);
+  }
+
+  // #endregion
+
   /**
    * Returns public org information.
    *
@@ -2934,14 +2968,16 @@ export class ApiClient extends BaseClient {
    *
    * @param env The environment to use
    * @param email The user's email
+   * @param headers Optional headers to set
    * @returns Empty response
    */
-  static async emailMyOrgs(env: EnvInterface, email: string) {
+  static async emailMyOrgs(env: EnvInterface, email: string, headers?: HeadersInit) {
     const o = op("/v0/email/orgs", "get");
     return await retryOn5XX(() =>
       o({
         baseUrl: env.SignerApiRoot,
         params: { query: { email } },
+        headers,
       }),
     ).then(assertOk);
   }
@@ -2956,6 +2992,7 @@ export class ApiClient extends BaseClient {
    * @param lifetimes Lifetimes of the new session.
    * @param mfaReceipt Optional MFA receipt(s)
    * @param purpose Optional session description.
+   * @param headers Additional headers to set
    * @returns The session data.
    */
   static async oidcSessionCreate(
@@ -2966,18 +3003,16 @@ export class ApiClient extends BaseClient {
     lifetimes?: RatchetConfig,
     mfaReceipt?: MfaReceipts,
     purpose?: string,
+    headers?: HeadersInit,
   ): Promise<CubeSignerResponse<SessionData>> {
     const o = op("/v0/org/{org_id}/oidc", "post");
 
-    const loginFn = async (headers?: HeadersInit) => {
+    const loginFn = async (mfaHeaders?: HeadersInit) => {
       const data = await retryOn5XX(() =>
         o({
           baseUrl: env.SignerApiRoot,
           params: { path: { org_id: orgId } },
-          headers: {
-            ...headers,
-            Authorization: token,
-          },
+          headers: mergeHeaders(headers, mfaHeaders, authHeader(token)),
           body: {
             scopes,
             purpose,
@@ -3013,12 +3048,14 @@ export class ApiClient extends BaseClient {
    * @param env The environment to use
    * @param orgId The org to login to
    * @param body The request body
+   * @param headers Optional headers to set
    * @returns The challenge that needs to be answered via {@link siweLoginComplete}
    */
   static async siweLoginInit(
     env: EnvInterface,
     orgId: string,
     body: schemas["SiweInitRequest"],
+    headers?: HeadersInit,
   ): Promise<schemas["SiweInitResponse"]> {
     const o = op("/v0/org/{org_id}/oidc/siwe", "post");
     return await retryOn5XX(() =>
@@ -3026,6 +3063,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body,
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3040,12 +3078,14 @@ export class ApiClient extends BaseClient {
    * @param env The environment to use
    * @param orgId The org to login to
    * @param body The request body
+   * @param headers Optional headers to set
    * @returns An OIDC token which can be used to log in via OIDC (see {@link oidcSessionCreate})
    */
   static async siweLoginComplete(
     env: EnvInterface,
     orgId: string,
     body: schemas["SiweCompleteRequest"],
+    headers?: HeadersInit,
   ): Promise<schemas["SiweCompleteResponse"]> {
     const o = op("/v0/org/{org_id}/oidc/siwe", "patch");
     return await retryOn5XX(() =>
@@ -3053,6 +3093,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body,
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3062,17 +3103,20 @@ export class ApiClient extends BaseClient {
    *
    * @param env The environment to log into
    * @param body The login request
+   * @param headers Optional headers to set
    * @returns The challenge that must be answered (see {@link passkeyLoginComplete}) to log in.
    */
   static async passkeyLoginInit(
     env: EnvInterface,
     body: LoginRequest,
+    headers?: HeadersInit,
   ): Promise<PasskeyLoginChallenge> {
     const o = op("/v0/passkey", "post");
     const resp = await retryOn5XX(() =>
       o({
         baseUrl: env.SignerApiRoot,
         body,
+        headers,
       }),
     ).then(assertOk);
     return new PasskeyLoginChallenge(env, resp, body.purpose);
@@ -3084,18 +3128,21 @@ export class ApiClient extends BaseClient {
    * @param env The environment to log into
    * @param body The request body
    * @param purpose Optional descriptive session purpose
+   * @param headers Optional headers to set
    * @returns The session data
    */
   static async passkeyLoginComplete(
     env: EnvInterface,
     body: PasskeyAssertAnswer,
     purpose?: string | null,
+    headers?: HeadersInit,
   ): Promise<SessionData> {
     const o = op("/v0/passkey", "patch");
     const resp = await retryOn5XX(() =>
       o({
         baseUrl: env.SignerApiRoot,
         body,
+        headers,
       }),
     ).then(assertOk);
     return {
@@ -3117,11 +3164,13 @@ export class ApiClient extends BaseClient {
    * @param env The environment to log into
    * @param orgId The id of the organization
    * @param body The request body
+   * @param headers Optional headers to set
    */
   static async idpAcceptInvite(
     env: EnvInterface,
     orgId: string,
     body: InvitationAcceptRequest,
+    headers?: HeadersInit,
   ): Promise<void> {
     const o = op("/v0/org/{org_id}/invitation/accept", "post");
     await retryOn5XX(() =>
@@ -3129,6 +3178,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body,
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3139,6 +3189,7 @@ export class ApiClient extends BaseClient {
    * @param env The environment to log into
    * @param orgId The id of the organization
    * @param body The request body
+   * @param headers Optional headers to set
    * @returns Returns an OIDC token which can be used
    *   to log in via OIDC (see {@link oidcSessionCreate}).
    */
@@ -3146,6 +3197,7 @@ export class ApiClient extends BaseClient {
     env: EnvInterface,
     orgId: string,
     body: AuthenticationRequest,
+    headers?: HeadersInit,
   ): Promise<AuthenticationResponse> {
     const o = op("/v0/org/{org_id}/idp/authenticate", "post");
     return retryOn5XX(() =>
@@ -3153,6 +3205,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body,
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3163,12 +3216,14 @@ export class ApiClient extends BaseClient {
    * @param env The environment to log into
    * @param orgId The id of the organization
    * @param body The request body
+   * @param headers Optional headers to set
    * @returns Returns the partial token (`${header}.${claims}.`) while the signature is sent via email.
    */
   static async idpPasswordResetRequest(
     env: EnvInterface,
     orgId: string,
     body: PasswordResetRequest,
+    headers?: HeadersInit,
   ): Promise<EmailOtpResponse> {
     const o = op("/v0/org/{org_id}/idp/password_reset", "post");
     return retryOn5XX(() =>
@@ -3176,6 +3231,7 @@ export class ApiClient extends BaseClient {
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
         body,
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3188,6 +3244,7 @@ export class ApiClient extends BaseClient {
    * @param partialToken The partial token returned by {@link passwordResetRequest}
    * @param signature The one-time code (signature in this case) sent via email
    * @param newPassword The new password
+   * @param headers Optional headers to set
    */
   static async idpPasswordResetConfirm(
     env: EnvInterface,
@@ -3195,6 +3252,7 @@ export class ApiClient extends BaseClient {
     partialToken: string,
     signature: string,
     newPassword: string,
+    headers?: HeadersInit,
   ): Promise<void> {
     const o = op("/v0/org/{org_id}/idp/password_reset", "patch");
     await retryOn5XX(() =>
@@ -3205,6 +3263,7 @@ export class ApiClient extends BaseClient {
           token: `${partialToken}${signature}`,
           new_password: newPassword,
         },
+        headers,
       }),
     ).then(assertOk);
   }
@@ -3215,21 +3274,21 @@ export class ApiClient extends BaseClient {
    * @param env The environment to log into
    * @param orgId The org id in which to generate proof
    * @param token The oidc token
+   * @param headers Optional headers to set
    * @returns Proof of authentication
    */
   static async identityProveOidc(
     env: EnvInterface,
     orgId: string,
     token: string,
+    headers?: HeadersInit,
   ): Promise<IdentityProof> {
     const o = op("/v0/org/{org_id}/identity/prove/oidc", "post");
     return retryOn5XX(() =>
       o({
         baseUrl: env.SignerApiRoot,
         params: { path: { org_id: orgId } },
-        headers: {
-          Authorization: token,
-        },
+        headers: mergeHeaders(headers, authHeader(token)),
       }),
     ).then(assertOk);
   }
@@ -3239,16 +3298,19 @@ export class ApiClient extends BaseClient {
    *
    * @param env The environment to log into
    * @param token The oidc token identifying the user
+   * @param headers Optional headers to set
    * @returns The organization the user belongs to
    */
-  static async userOrgs(env: EnvInterface, token: string): Promise<UserOrgsResponse> {
+  static async userOrgs(
+    env: EnvInterface,
+    token: string,
+    headers?: HeadersInit,
+  ): Promise<UserOrgsResponse> {
     const o = op("/v0/user/orgs", "get");
     return retryOn5XX(() =>
       o({
         baseUrl: env.SignerApiRoot,
-        headers: {
-          Authorization: token,
-        },
+        headers: mergeHeaders(headers, authHeader(token)),
       }),
     ).then(assertOk);
   }

package/src/client/base_client.ts

@@ -9,6 +9,7 @@ import type { SessionData, SessionManager, SessionMetadata } from "./session";
 import { MemorySessionManager, metadata, parseBase64SessionData } from "./session";
 import type { NewSessionResponse, ErrorResponse } from "../schema_types";
 import type { EnvInterface } from "../env";
+import { mergeHeaders } from "openapi-fetch";
 
 /** CubeSigner SDK package name */
 export const NAME: string = pkg.name;
@@ -163,14 +164,16 @@ export class BaseClient extends EventEmitter<ClientEvents> {
       // If we have an activeSession, let it dictate the baseUrl. Otherwise fall back to the one set at construction
       baseUrl,
       ...opts,
-      headers: {
-        "User-Agent": browserUserAgent ?? `${NAME}@${VERSION}`,
-        "X-Cubist-Ts-Sdk": `${NAME}@${VERSION}`,
-        Origin: this.config.origin,
-        Authorization: token,
-        ...(this.config.headers ?? {}),
-        ...opts.headers,
-      },
+      headers: mergeHeaders(
+        {
+          "User-Agent": browserUserAgent ?? `${NAME}@${VERSION}`,
+          "X-Cubist-Ts-Sdk": `${NAME}@${VERSION}`,
+          Origin: this.config.origin,
+        },
+        authHeader(token),
+        this.config.headers,
+        opts.headers,
+      ),
       params: {
         ...opts.params,
         path: {
@@ -249,7 +252,7 @@ export class BaseClient extends EventEmitter<ClientEvents> {
           return status >= 500 && status < 600;
         },
       });
-      // Once we have a non-5XX response, we will assertOk (either throwing or yielding the reponse)
+      // Once we have a non-5XX response, we will assertOk (either throwing or yielding the response)
       return assertOk(resp);
     } catch (e) {
       if (e instanceof ErrResponse) {
@@ -308,3 +311,13 @@ export type OmitAutoParams<O> = DeepOmit<
     params: { path: { org_id: string } };
   }
 > & { params?: { path?: Record<string, unknown> } };
+
+/**
+ * Creates {@link HeadersInit} containing a single "Authorization" header with a given value.
+ *
+ * @param token The "Authorization" header value
+ * @returns A {@link HeadersInit} object containing a single "Authorization" header with a given value.
+ */
+export function authHeader(token: string): HeadersInit {
+  return { Authorization: token };
+}

package/src/client.ts

@@ -1,19 +1,11 @@
 import { ApiClient } from "./client/api_client";
-import type { IdentityProof, RatchetConfig, EmailOtpResponse } from "./schema_types";
+import type { EmailOtpResponse, IdentityProof, RatchetConfig } from "./schema_types";
 
 // used in doc comments
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { AddFidoChallenge, TotpChallenge } from "./mfa";
 import { Org } from "./org";
-import type {
-  CubeSignerResponse,
-  EnvInterface,
-  MfaReceipts,
-  Scope,
-  SessionData,
-  SessionInfo,
-  SessionManager,
-} from ".";
+import type { MfaReceipts, SessionData, SessionInfo, SessionManager } from ".";
 import { Key } from ".";
 
 /** Options for logging in with OIDC token */
@@ -122,71 +114,45 @@ export class CubeSignerClient {
   }
 
   /**
-   * Exchange an OIDC token for a CubeSigner session token.
-   *
-   * @param env The environment to log into
-   * @param orgId The org to log into.
-   * @param token The OIDC token to exchange
-   * @param scopes The scopes for the new session
-   * @param lifetimes Lifetimes of the new session.
-   * @param mfaReceipt Optional MFA receipt(s)
-   * @param purpose Optional session description.
-   * @returns The session data.
+   * Create a new OIDC-backed session.
+   *
+   * Same as {@link ApiClient.oidcSessionCreate}, see its documentation for more details.
+   *
+   * @param args Request arguments
+   * @returns The new session data
    */
   static async createOidcSession(
-    env: EnvInterface,
-    orgId: string,
-    token: string,
-    scopes: Array<Scope>,
-    lifetimes?: RatchetConfig,
-    mfaReceipt?: MfaReceipts,
-    purpose?: string,
-  ): Promise<CubeSignerResponse<SessionData>> {
-    return await ApiClient.oidcSessionCreate(
-      env,
-      orgId,
-      token,
-      scopes,
-      lifetimes,
-      mfaReceipt,
-      purpose,
-    );
+    ...args: Parameters<typeof ApiClient.oidcSessionCreate>
+  ): Promise<Awaited<ReturnType<typeof ApiClient.oidcSessionCreate>>> {
+    return await ApiClient.oidcSessionCreate(...args);
   }
 
   /**
-   * Exchange an OIDC token for a proof of authentication.
+   * Prove an OIDC identity.
+   *
+   * Same as {@link ApiClient.identityProveOidc}, see its documentation for more details.
    *
-   * @param env The environment to log into
-   * @param orgId The org id in which to generate proof
-   * @param token The oidc token
+   * @param args Request arguments
    * @returns Proof of authentication
    */
   static async proveOidcIdentity(
-    env: EnvInterface,
-    orgId: string,
-    token: string,
+    ...args: Parameters<typeof ApiClient.identityProveOidc>
   ): Promise<IdentityProof> {
-    return await ApiClient.identityProveOidc(env, orgId, token);
+    return await ApiClient.identityProveOidc(...args);
   }
 
   /**
-   * Initiates login via Email OTP.
-   * Returns an unsigned OIDC token and sends an email to the user containing the signature of that token.
-   * The OIDC token can be reconstructed by appending the signature to the partial token like so:
+   * Initialize email OTP authentication.
    *
-   * token = partial_token + signature
+   * Same as {@link ApiClient.initEmailOtpAuth}, see its documentation for more details.
    *
-   * @param env The environment to use
-   * @param orgId The org to login to
-   * @param email The email to send the signature to
-   * @returns The partial OIDC token that must be combined with the signature in the email
+   * @param args Request arguments
+   * @returns — The partial OIDC token that must be combined with the signature in the email
    */
   static async initEmailOtpAuth(
-    env: EnvInterface,
-    orgId: string,
-    email: string,
+    ...args: Parameters<typeof ApiClient.initEmailOtpAuth>
   ): Promise<EmailOtpResponse> {
-    return await ApiClient.initEmailOtpAuth(env, orgId, email);
+    return await ApiClient.initEmailOtpAuth(...args);
   }
 
   /**

package/src/fetch.ts

@@ -181,7 +181,7 @@ export type FetchResponseSuccessData<T> = Required<FetchResponse<T>>["data"];
 export function assertOk<T>(resp: FetchResponse<T>): FetchResponseSuccessData<T> {
   if (!resp.response.ok) {
     const errResp = resp.error as unknown as ErrorResponse | undefined;
-    const error = new ErrResponse({
+    throw new ErrResponse({
       requestId: errResp?.request_id,
       message: errResp?.message,
       statusText: resp.response?.statusText,
@@ -189,7 +189,6 @@ export function assertOk<T>(resp: FetchResponse<T>): FetchResponseSuccessData<T>
       url: resp.response?.url,
       errorCode: errResp?.error_code,
     });
-    throw error;
   }
   return resp.data!;
 }

package/src/key.ts

@@ -29,6 +29,7 @@ import type {
   DiffieHellmanResponse,
   KeyInfoJwt,
   KeyAttestationQuery,
+  BinanceApiProperties,
 } from "./schema_types";
 import type {
   ApiClient,
@@ -99,6 +100,7 @@ export enum Ed25519 {
   Stellar = "Ed25519StellarAddr",
   Substrate = "Ed25519SubstrateAddr",
   Tendermint = "Ed25519TendermintAddr",
+  BinanceApi = "Ed25519BinanceApi",
   Ton = "Ed25519TonAddr",
   Xrp = "Ed25519XrpAddr",
 }
@@ -125,6 +127,9 @@ export type BabyJubjub = typeof BabyJubjub;
 /** Key type */
 export type KeyType = Secp256k1 | Bls | Ed25519 | Mnemonic | Stark | P256 | BabyJubjub;
 
+/** The type representing all different kinds of key properties. */
+export type KeyPropertiesPatch = { kind: "BinanceApi" } & BinanceApiProperties;
+
 /**
  * A representation of a signing key.
  */
@@ -265,6 +270,23 @@ export class Key {
     return await this.update({ metadata }, mfaReceipt);
   }
 
+  /**
+   * Set key properties. Each field in the provided patch is independent: missing
+   * means leave alone, `null` clears, a value sets. Sending `null` for the whole
+   * field clears all properties on the key.
+   *
+   * @param patch Type-specific properties
+   * @param mfaReceipt Optional MFA receipt(s)
+   * @throws if MFA is required and no receipts are provided
+   * @returns The updated key info
+   */
+  async setProperties(
+    patch: KeyPropertiesPatch | null,
+    mfaReceipt?: MfaReceipts,
+  ): Promise<KeyInfo> {
+    return await this.update({ properties: patch }, mfaReceipt);
+  }
+
   /**
    * Retrieves the existing metadata, asserts that it is an object (throws if it is not),
    * then sets the value of the {@link name} property in that object to {@link value},
@@ -820,6 +842,8 @@ export function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
       return Ed25519.Tendermint;
     case "Ed25519TonAddr":
       return Ed25519.Ton;
+    case "Ed25519BinanceApi":
+      return Ed25519.BinanceApi;
     case "Stark":
       return Stark;
     case "Mnemonic":