@cubist-labs/cubesigner-sdk 0.1.26 → 0.1.77

package/src/signer_session.ts

@@ -1,10 +1,22 @@
 import assert from "assert";
-import { CubeSigner, Key, OidcSessionManager, OidcSessionStorage, Org } from ".";
+import {
+  CubeSigner,
+  Key,
+  toKeyInfo,
+  Org,
+  KeyInfo,
+  MfaReceipt,
+  IdentityProof,
+  MfaFidoChallenge,
+} from ".";
 import { components, paths } from "./client";
-import { assertOk } from "./util";
-import { SignerSessionManager, SignerSessionStorage } from "./session/signer_session_manager";
-
-export type KeyInfo = components["schemas"]["KeyInfo"];
+import { JsonMap, assertOk } from "./util";
+import { PublicKeyCredential } from "./fido";
+import {
+  NewSessionResponse,
+  SignerSessionManager,
+  SignerSessionStorage,
+} from "./session/signer_session_manager";
 
 /* eslint-disable */
 export type EvmSignRequest =
@@ -20,7 +32,9 @@ export type BlobSignRequest =
 export type BtcSignRequest =
   paths["/v0/org/{org_id}/btc/sign/{pubkey}"]["post"]["requestBody"]["content"]["application/json"];
 export type SolanaSignRequest =
-  paths["/v1/org/{org_id}/solana/sign/{pubkey}"]["post"]["requestBody"]["content"]["application/json"];
+  paths["/v0/org/{org_id}/solana/sign/{pubkey}"]["post"]["requestBody"]["content"]["application/json"];
+export type AvaSignRequest =
+  paths["/v0/org/{org_id}/ava/sign/{pubkey}"]["post"]["requestBody"]["content"]["application/json"];
 
 export type EvmSignResponse =
   components["responses"]["Eth1SignResponse"]["content"]["application/json"];
@@ -38,6 +52,8 @@ export type SolanaSignResponse =
   components["responses"]["SolanaSignResponse"]["content"]["application/json"];
 export type MfaRequestInfo =
   components["responses"]["MfaRequestInfo"]["content"]["application/json"];
+export type AvaSignResponse =
+  components["responses"]["AvaSignResponse"]["content"]["application/json"];
 
 export type AcceptedResponse = components["schemas"]["AcceptedResponse"];
 export type ErrorResponse = components["schemas"]["ErrorResponse"];
@@ -47,20 +63,61 @@ export type BtcSignatureKind = components["schemas"]["BtcSignatureKind"];
 /** MFA request kind */
 export type MfaType = components["schemas"]["MfaType"];
 
+/** Ava P- or X-chain transaction */
+export type AvaTx = { P: AvaPChainTx } | { X: AvaXChainTx };
+
+/** Ava P-chain transaction */
+export type AvaPChainTx =
+  | { AddPermissionlessValidator: JsonMap }
+  | { AddSubnetValidator: JsonMap }
+  | { AddValidator: JsonMap }
+  | { CreateChain: JsonMap }
+  | { CreateSubnet: JsonMap }
+  | { Export: JsonMap }
+  | { Import: JsonMap };
+
+/** Ava X-chain transaction */
+export type AvaXChainTx = { Base: JsonMap } | { Export: JsonMap } | { Import: JsonMap };
+
 type SignFn<U> = (headers?: HeadersInit) => Promise<U | AcceptedResponse>;
 
+export interface MfaRequired {
+  /** Org id */
+  org_id: string;
+  /** MFA request id */
+  id: string;
+  /** Optional MFA session */
+  session?: NewSessionResponse | null;
+}
+
 /**
- * A response of a signing request.
+ * A response of a CubeSigner request.
  */
 export class SignResponse<U> {
-  readonly #cs: CubeSigner;
-  readonly #orgId: string;
   readonly #signFn: SignFn<U>;
   readonly #resp: U | AcceptedResponse;
+  /**
+   * Optional MFA id. Only set if there is an MFA request associated with the
+   * signing request
+   */
+  readonly #mfaRequired?: MfaRequired;
+
+  /** @return {string} The MFA id associated with this request */
+  mfaId(): string {
+    return this.#mfaRequired!.id;
+  }
 
-  /** @return {boolean} True if this signing request requires an MFA approval */
+  /** @return {boolean} True if this request requires an MFA approval */
   requiresMfa(): boolean {
-    return (this.#resp as AcceptedResponse).accepted?.MfaRequired !== undefined;
+    return this.#mfaRequired !== undefined;
+  }
+
+  /**
+   * Returns session information to use for any MFA approval requests (if any was included in the response).
+   * @return {ClientSessionInfo | undefined}
+   */
+  mfaSessionInfo(): NewSessionResponse | undefined {
+    return (this.#resp as AcceptedResponse).accepted?.MfaRequired?.session ?? undefined;
   }
 
   /** @return {U} The signed data */
@@ -69,47 +126,56 @@ export class SignResponse<U> {
   }
 
   /**
-   * Approves the MFA request using a given signer session and a TOTP code.
-   *
-   * Note: This only works for MFA requests that require a single approval.
+   * Approves the MFA request using a given session and a TOTP code.
    *
    * @param {SignerSession} session Signer session to use
    * @param {string} code 6-digit TOTP code
    * @return {SignResponse<U>} The result of signing with the approval
    */
   async approveTotp(session: SignerSession, code: string): Promise<SignResponse<U>> {
-    const mfaId = this.#mfaId();
-
+    assert(this.requiresMfa());
+    const mfaId = this.mfaId();
+    const mfaOrgId = this.#mfaRequired!.org_id;
     const mfaApproval = await session.totpApprove(mfaId, code);
     assert(mfaApproval.id === mfaId);
     const mfaConf = mfaApproval.receipt?.confirmation;
 
     if (!mfaConf) {
-      throw new Error("MfaRequest has not been approved yet");
+      return this;
     }
 
-    return await this.#signWithMfaApproval(mfaConf!);
+    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
   }
 
   /**
-   * Approves the MFA request using CubeSigner's management session.
-   *
-   * Note: This only works for MFA requests that require a single approval.
+   * Approves the MFA request using a given `CubeSigner` instance (i.e., its management session).
    *
+   * @param {CubeSigner} cs CubeSigner whose session to use
    * @return {SignResponse<U>} The result of signing with the approval
    */
-  async approve(): Promise<SignResponse<U>> {
-    const mfaId = this.#mfaId();
+  async approve(cs: CubeSigner): Promise<SignResponse<U>> {
+    assert(this.requiresMfa());
+    const mfaId = this.#mfaRequired!.id;
+    const mfaOrgId = this.#mfaRequired!.org_id;
 
-    const mfaApproval = await Org.mfaApprove(this.#cs, this.#orgId, mfaId);
+    const mfaApproval = await Org.mfaApprove(cs, mfaOrgId, mfaId);
     assert(mfaApproval.id === mfaId);
     const mfaConf = mfaApproval.receipt?.confirmation;
 
     if (!mfaConf) {
-      throw new Error("MfaRequest has not been approved yet");
+      return this;
     }
 
-    return await this.#signWithMfaApproval(mfaConf);
+    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
+  }
+
+  /**
+   * @param {MfaReceipt} mfaReceipt The MFA receipt
+   * @return {Promise<SignResponse<U>>} The result of signing after MFA approval
+   */
+  async signWithMfaApproval(mfaReceipt: MfaReceipt): Promise<SignResponse<U>> {
+    const headers = SignResponse.getMfaHeaders(mfaReceipt);
+    return new SignResponse(this.#signFn, await this.#signFn(headers));
   }
 
   // --------------------------------------------------------------------------
@@ -119,44 +185,45 @@ export class SignResponse<U> {
   /**
    * Constructor.
    *
-   * @param {CubeSigner} cs The CubeSigner instance to use for requests
-   * @param {string} orgId The org id of the corresponding signing request
    * @param {SignFn} signFn The signing function that this response is from.
    *                        This argument is used to resend requests with
    *                        different headers if needed.
    * @param {U | AcceptedResponse} resp The response as returned by the OpenAPI
    *                                    client.
    */
-  constructor(cs: CubeSigner, orgId: string, signFn: SignFn<U>, resp: U | AcceptedResponse) {
-    this.#cs = cs;
-    this.#orgId = orgId;
+  constructor(signFn: SignFn<U>, resp: U | AcceptedResponse) {
     this.#signFn = signFn;
     this.#resp = resp;
+    this.#mfaRequired = (this.#resp as AcceptedResponse).accepted?.MfaRequired;
   }
 
   /**
-   * @param {string} mfaConf MFA request approval confirmation code
-   * @return {Promise<SignResponse<U>>} The result of signing after MFA approval
+   * Static constructor.
+   * @param {SignFn} signFn The signing function that this response is from.
+   *                        This argument is used to resend requests with
+   *                        different headers if needed.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
+   * @return {Promise<SignResponse<U>>} New instance of this class.
    */
-  async #signWithMfaApproval(mfaConf: string): Promise<SignResponse<U>> {
-    const mfaId = this.#mfaId();
-
-    const headers = {
-      "x-cubist-mfa-id": mfaId,
-      "x-cubist-mfa-confirmation": mfaConf,
-    };
-    return new SignResponse(this.#cs, this.#orgId, this.#signFn, await this.#signFn(headers));
+  static async create<U>(signFn: SignFn<U>, mfaReceipt?: MfaReceipt): Promise<SignResponse<U>> {
+    const seed = await signFn(this.getMfaHeaders(mfaReceipt));
+    return new SignResponse(signFn, seed);
   }
 
   /**
-   * @return {string} MFA id if MFA is required for this response; throws otherwise.
+   * Returns HTTP headers containing a given MFA receipt.
+   *
+   * @param {MfaReceipt} mfaReceipt MFA receipt
+   * @return {HeadersInit} Headers including that receipt
    */
-  #mfaId(): string {
-    const mfaRequired = (this.#resp as AcceptedResponse).accepted?.MfaRequired;
-    if (!mfaRequired) {
-      throw new Error("Request does not require MFA approval");
-    }
-    return mfaRequired.id;
+  static getMfaHeaders(mfaReceipt?: MfaReceipt): HeadersInit | undefined {
+    return mfaReceipt
+      ? {
+          "x-cubist-mfa-id": mfaReceipt.mfaId,
+          "x-cubist-mfa-org-id": mfaReceipt.mfaOrgId,
+          "x-cubist-mfa-confirmation": mfaReceipt.mfaConf,
+        }
+      : undefined;
   }
 }
 
@@ -197,15 +264,19 @@ export class SignerSessionInfo {
 
 /** Signer session. */
 export class SignerSession {
-  readonly cs: CubeSigner;
-  sessionMgr: OidcSessionManager | SignerSessionManager;
+  sessionMgr: SignerSessionManager;
   readonly #orgId: string;
 
+  /** Org id */
+  get orgId() {
+    return this.#orgId;
+  }
+
   /**
    * Returns the list of keys that this token grants access to.
    * @return {Key[]} The list of keys.
    */
-  async keys(): Promise<Key[]> {
+  async keys(): Promise<KeyInfo[]> {
     const resp = await (
       await this.sessionMgr.client()
     ).get("/v0/org/{org_id}/token/keys", {
@@ -213,7 +284,7 @@ export class SignerSession {
       parseAs: "json",
     });
     const data = assertOk(resp);
-    return data.keys.map((k: KeyInfo) => new Key(this.cs, this.#orgId, k));
+    return data.keys.map((k) => toKeyInfo(k));
   }
 
   /**
@@ -234,13 +305,72 @@ export class SignerSession {
     return assertOk(resp);
   }
 
+  /**
+   * Initiate approval of an existing MFA request using FIDO.
+   * @param {string} mfaId The MFA request ID.
+   * @return {Promise<MfaFidoChallenge>} A challenge that needs to be answered to complete the approval.
+   */
+  async fidoApproveStart(mfaId: string): Promise<MfaFidoChallenge> {
+    const client = await this.sessionMgr.client();
+    const resp = await client.post("/v0/org/{org_id}/mfa/{mfa_id}/fido", {
+      params: { path: { org_id: this.#orgId, mfa_id: mfaId } },
+      parseAs: "json",
+    });
+    const challenge = assertOk(resp);
+    return new MfaFidoChallenge(this, mfaId, challenge);
+  }
+
+  /**
+   * Complete a previously initiated MFA request approval using FIDO.
+   * @param {string} mfaId The MFA request ID
+   * @param {string} challengeId The challenge ID
+   * @param {PublicKeyCredential} credential The answer to the challenge
+   * @return {Promise<MfaRequestInfo>} The current status of the MFA request.
+   */
+  async fidoApproveComplete(
+    mfaId: string,
+    challengeId: string,
+    credential: PublicKeyCredential,
+  ): Promise<MfaRequestInfo> {
+    const client = await this.sessionMgr.client();
+    const resp = await client.patch("/v0/org/{org_id}/mfa/{mfa_id}/fido", {
+      params: { path: { org_id: this.#orgId, mfa_id: mfaId } },
+      body: {
+        challenge_id: challengeId,
+        credential,
+      },
+      parseAs: "json",
+    });
+    return assertOk(resp);
+  }
+
+  /**
+   * Get a pending MFA request by its id.
+   * @param {CubeSigner} cs Management session to use (this argument will be removed in future versions)
+   * @param {string} mfaId The id of the MFA request.
+   * @return {Promise<MfaRequestInfo>} The MFA request.
+   */
+  async getMfaInfo(cs: CubeSigner, mfaId: string): Promise<MfaRequestInfo> {
+    const resp = await (
+      await cs.management()
+    ).get("/v0/org/{org_id}/mfa/{mfa_id}", {
+      params: { path: { org_id: this.#orgId, mfa_id: mfaId } },
+    });
+    return assertOk(resp);
+  }
+
   /**
    * Submit an EVM sign request.
    * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
    * @param {EvmSignRequest} req What to sign.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt.
    * @return {Promise<EvmSignResponse | AcceptedResponse>} Signature
    */
-  async signEvm(key: Key | string, req: EvmSignRequest): Promise<SignResponse<EvmSignResponse>> {
+  async signEvm(
+    key: Key | string,
+    req: EvmSignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<EvmSignResponse>> {
     const pubkey = typeof key === "string" ? (key as string) : key.materialId;
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
@@ -253,16 +383,21 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Submit an 'eth2' sign request.
    * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
    * @param {Eth2SignRequest} req What to sign.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<Eth2SignResponse | AcceptedResponse>} Signature
    */
-  async signEth2(key: Key | string, req: Eth2SignRequest): Promise<SignResponse<Eth2SignResponse>> {
+  async signEth2(
+    key: Key | string,
+    req: Eth2SignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<Eth2SignResponse>> {
     const pubkey = typeof key === "string" ? (key as string) : key.materialId;
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
@@ -275,15 +410,19 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Sign a stake request.
    * @param {Eth2StakeRequest} req The request to sign.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<Eth2StakeResponse | AcceptedResponse>} The response.
    */
-  async stake(req: Eth2StakeRequest): Promise<SignResponse<Eth2StakeResponse>> {
+  async stake(
+    req: Eth2StakeRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<Eth2StakeResponse>> {
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
         await this.sessionMgr.client()
@@ -295,18 +434,20 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Sign an unstake request.
    * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
    * @param {Eth2UnstakeRequest} req The request to sign.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<Eth2UnstakeResponse | AcceptedResponse>} The response.
    */
   async unstake(
     key: Key | string,
     req: Eth2UnstakeRequest,
+    mfaReceipt?: MfaReceipt,
   ): Promise<SignResponse<Eth2UnstakeResponse>> {
     const pubkey = typeof key === "string" ? (key as string) : key.materialId;
     const sign = async (headers?: HeadersInit) => {
@@ -320,16 +461,21 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Sign a raw blob.
    * @param {Key | string} key The key to sign with (either {@link Key} or its ID).
    * @param {BlobSignRequest} req What to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<BlobSignResponse | AcceptedResponse>} The response.
    */
-  async signBlob(key: Key | string, req: BlobSignRequest): Promise<SignResponse<BlobSignResponse>> {
+  async signBlob(
+    key: Key | string,
+    req: BlobSignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<BlobSignResponse>> {
     const key_id = typeof key === "string" ? (key as string) : key.id;
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
@@ -344,16 +490,21 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Sign a bitcoin message.
    * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
    * @param {BtcSignRequest} req What to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<BtcSignResponse | AcceptedResponse>} The response.
    */
-  async signBtc(key: Key | string, req: BtcSignRequest): Promise<SignResponse<BtcSignResponse>> {
+  async signBtc(
+    key: Key | string,
+    req: BtcSignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<BtcSignResponse>> {
     const pubkey = typeof key === "string" ? (key as string) : key.materialId;
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
@@ -368,24 +519,26 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
    * Sign a solana message.
    * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
    * @param {SolanaSignRequest} req What to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
    * @return {Promise<SolanaSignResponse | AcceptedResponse>} The response.
    */
   async signSolana(
     key: Key | string,
     req: SolanaSignRequest,
+    mfaReceipt?: MfaReceipt,
   ): Promise<SignResponse<SolanaSignResponse>> {
     const pubkey = typeof key === "string" ? (key as string) : key.materialId;
     const sign = async (headers?: HeadersInit) => {
       const resp = await (
         await this.sessionMgr.client()
-      ).post("/v1/org/{org_id}/solana/sign/{pubkey}", {
+      ).post("/v0/org/{org_id}/solana/sign/{pubkey}", {
         params: { path: { org_id: this.#orgId, pubkey } },
         body: req,
         headers,
@@ -393,45 +546,69 @@ export class SignerSession {
       });
       return assertOk(resp);
     };
-    return new SignResponse(this.cs, this.#orgId, sign, await sign());
+    return await SignResponse.create(sign, mfaReceipt);
   }
 
   /**
-   * Loads an existing signer session from storage.
-   * @param {CubeSigner} cs The CubeSigner instance
-   * @param {SignerSessionStorage} storage The session storage to use
-   * @return {Promise<SingerSession>} New signer session
+   * Sign an Avalanche P- or X-chain message.
+   * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
+   * @param {AvaTx} tx Avalanche message (transaction) to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
+   * @return {Promise<AvaSignResponse | AcceptedResponse>} The response.
+   */
+  async signAva(
+    key: Key | string,
+    tx: AvaTx,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<SignResponse<AvaSignResponse>> {
+    const pubkey = typeof key === "string" ? (key as string) : key.materialId;
+    const sign = async (headers?: HeadersInit) => {
+      const req = <AvaSignRequest>{
+        tx: tx as unknown,
+      };
+      const resp = await (
+        await this.sessionMgr.client()
+      ).post("/v0/org/{org_id}/ava/sign/{pubkey}", {
+        params: { path: { org_id: this.#orgId, pubkey } },
+        body: req,
+        headers,
+        parseAs: "json",
+      });
+      return assertOk(resp);
+    };
+    return await SignResponse.create(sign, mfaReceipt);
+  }
+
+  /**
+   * Obtain a proof of authentication.
+   *
+   * @return {Promise<IdentityProof>} Proof of authentication
    */
-  static async loadSignerSession(
-    cs: CubeSigner,
-    storage: SignerSessionStorage,
-  ): Promise<SignerSession> {
-    const manager = await SignerSessionManager.loadFromStorage(cs, storage);
-    return new SignerSession(cs, manager);
+  async proveIdentity(): Promise<IdentityProof> {
+    const client = await this.sessionMgr.client();
+    const resp = await client.post("/v0/org/{org_id}/identity/prove", {
+      params: { path: { org_id: this.#orgId } },
+      parseAs: "json",
+    });
+    return assertOk(resp);
   }
 
   /**
-   * Loads an existing OIDC session from storage
-   * @param {CubeSigner} cs The CubeSigner instance
-   * @param {OidcSessionStorage} storage The storage to use
-   * @return {Promise<SignerSession>} New signer session
+   * Loads an existing signer session from storage.
+   * @param {SignerSessionStorage} storage The session storage to use
+   * @return {Promise<SingerSession>} New signer session
    */
-  static async loadOidcSession(
-    cs: CubeSigner,
-    storage: OidcSessionStorage,
-  ): Promise<SignerSession> {
-    const manager = await OidcSessionManager.loadFromStorage(storage);
-    return new SignerSession(cs, manager);
+  static async loadSignerSession(storage: SignerSessionStorage): Promise<SignerSession> {
+    const manager = await SignerSessionManager.loadFromStorage(storage);
+    return new SignerSession(manager);
   }
 
   /**
    * Constructor.
-   * @param {CubeSigner} cs The CubeSigner instance to use for requests
-   * @param {OidcSessionManager | SignerSessionManager} sessionMgr The session manager to use
+   * @param {SignerSessionManager} sessionMgr The session manager to use
    * @internal
    */
-  constructor(cs: CubeSigner, sessionMgr: OidcSessionManager | SignerSessionManager) {
-    this.cs = cs;
+  constructor(sessionMgr: SignerSessionManager) {
     this.sessionMgr = sessionMgr;
     this.#orgId = sessionMgr.orgId;
   }

package/src/util.ts

@@ -1,5 +1,13 @@
 import * as path from "path";
 
+/** JSON map type */
+export interface JsonMap {
+  [member: string]: string | number | boolean | null | JsonArray | JsonMap;
+}
+
+/** JSON array type */
+export type JsonArray = Array<string | number | boolean | null | JsonArray | JsonMap>;
+
 /**
  * Directory where CubeSigner stores config files.
  * @return {string} Config dir
@@ -56,3 +64,36 @@ export function assertOk<D, T>(resp: ResponseType<D, T>, description?: string):
   }
   return resp.data;
 }
+
+/**
+ * Browser-friendly helper for decoding a 'base64url'-encoded string into a byte array.
+ *
+ * @param {string} b64url The 'base64url'-encoded string to decode
+ * @return {Uint8Array} Decoded byte array
+ */
+export function decodeBase64Url(b64url: string): Uint8Array {
+  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/").replace(/=*$/g, "");
+
+  // NOTE: there is no "base64url" encoding in the "buffer" module for the browser (unlike in node.js)
+  return typeof Buffer === "function"
+    ? Buffer.from(b64, "base64")
+    : Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+/**
+ * Browser-friendly helper for encoding a byte array into a 'base64url`-encoded string.
+ *
+ * @param {Iterable<number>} buffer The byte array to encode
+ * @return {string} The 'base64url' encoding of the byte array.
+ */
+export function encodeToBase64Url(buffer: Iterable<number>): string {
+  const bytes = new Uint8Array(buffer);
+
+  // NOTE: there is no "base64url" encoding in the "buffer" module for the browser (unlike in node.js)
+  const b64 =
+    typeof Buffer === "function"
+      ? Buffer.from(bytes).toString("base64")
+      : btoa(bytes.reduce((s, b) => s + String.fromCharCode(b), ""));
+
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=*$/g, "");
+}