@cubist-labs/cubesigner-sdk 0.2.17 → 0.2.21

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@cubist-labs/cubesigner-sdk",
     "author": "Cubist, Inc.",
-    "version": "0.2.17",
+    "version": "0.2.21",
     "description": "CubeSigner TypeScript SDK",
     "homepage": "https://github.com/cubist-labs/CubeSigner-TypeScript-SDK",
     "bugs": "https://github.com/cubist-labs/CubeSigner-TypeScript-SDK/issues",
@@ -33,19 +33,19 @@
     },
     "devDependencies": {
         "@hpke/core": "^1.2.5",
-        "@types/chai": "^4.3.5",
+        "@types/chai": "^4.3.11",
         "@types/chai-as-promised": "^7.1.8",
         "@types/jest": "^29.5.10",
         "@types/node": "^20.9.2",
         "@types/node-fetch": "^2.6.9",
         "@types/tmp": "^0.2.3",
-        "@typescript-eslint/eslint-plugin": "^6.12.0",
-        "chai": "^4.3.7",
+        "@typescript-eslint/eslint-plugin": "^6.13.1",
+        "chai": "^4.3.10",
         "chai-as-promised": "^7.1.1",
         "dotenv": "^16.3.1",
-        "eslint": "^8.54.0",
+        "eslint": "^8.55.0",
         "eslint-config-google": "^0.14.0",
-        "eslint-config-prettier": "^8.8.0",
+        "eslint-config-prettier": "^9.1.0",
         "jest": "^29.7.0",
         "openapi-typescript": "^6.7.1",
         "otplib": "^12.0.1",

package/dist/src/api.d.ts

@@ -1,16 +1,107 @@
-import createClient from "openapi-fetch";
-import { paths } from "./schema";
+import createClient, { FetchOptions, FetchResponse, FilterKeys, HttpMethod, PathsWith } from "openapi-fetch";
+import { paths, operations } from "./schema";
 import { SignerSessionData, SignerSessionLifetime, SignerSessionManager } from "./session/signer_session_manager";
-import { CreateOidcUserOptions, IdentityProof, KeyInRoleInfo, KeyInfoApi, ListKeysResponse, ListRoleKeysResponse, ListRoleUsersResponse, ListRolesResponse, OidcIdentity, SessionsResponse, PublicKeyCredential, RoleInfo, UpdateKeyRequest, UpdateOrgRequest, UpdateOrgResponse, UpdateRoleRequest, UserIdInfo, UserInRoleInfo, UserInfo, SessionInfo, OrgInfo, RatchetConfig, EvmSignRequest, EvmSignResponse, Eth2SignRequest, Eth2SignResponse, Eth2StakeRequest, Eth2StakeResponse, Eth2UnstakeRequest, Eth2UnstakeResponse, BlobSignRequest, BlobSignResponse, BtcSignResponse, BtcSignRequest, SolanaSignRequest, SolanaSignResponse, AvaSignResponse, AvaTx, MfaRequestInfo, MemberRole, UserExportCompleteResponse, UserExportInitResponse, UserExportListResponse } from "./schema_types";
+import { CreateOidcUserOptions, IdentityProof, KeyInRoleInfo, KeyInfoApi, ListKeysResponse, ListRoleKeysResponse, ListRoleUsersResponse, ListRolesResponse, OidcIdentity, SessionsResponse, PublicKeyCredential, RoleInfo, UpdateKeyRequest, UpdateOrgRequest, UpdateOrgResponse, UpdateRoleRequest, UserIdInfo, UserInRoleInfo, UserInfo, SessionInfo, OrgInfo, RatchetConfig, EvmSignRequest, EvmSignResponse, Eth2SignRequest, Eth2SignResponse, Eth2StakeRequest, Eth2StakeResponse, Eth2UnstakeRequest, Eth2UnstakeResponse, BlobSignRequest, BlobSignResponse, BtcSignResponse, BtcSignRequest, SolanaSignRequest, SolanaSignResponse, AvaSignResponse, AvaTx, MfaRequestInfo, MemberRole, UserExportCompleteResponse, UserExportInitResponse, UserExportListResponse, Empty } from "./schema_types";
 import { AddFidoChallenge, MfaFidoChallenge, MfaReceipt, TotpChallenge } from "./mfa";
 import { CubeSignerResponse } from "./response";
 import { Key, KeyType } from "./key";
 import { PageOpts, Paginator } from "./paginator";
 import { KeyPolicy } from "./role";
 import { EnvInterface } from "./env";
+import { EventEmitter } from "./events";
 /** @internal */
 export type Client = ReturnType<typeof createClient<paths>>;
-export { paths };
+export { paths, operations };
+/**
+ * Omit routes in {@link T} whose methods are all 'never'
+ */
+type OmitNeverPaths<T extends paths> = {
+    [p in keyof T as T[p] extends {
+        [m in keyof T[p]]: never;
+    } ? never : p]: T[p];
+};
+/**
+ * Filter out methods that don't match operation {@link Op}
+ */
+type FilterPaths<Op extends keyof operations> = {
+    [p in keyof paths]: {
+        [m in HttpMethod as m extends keyof paths[p] ? m : never]: m extends keyof paths[p] ? operations[Op] extends paths[p][m] ? paths[p][m] extends operations[Op] ? operations[Op] : never : never : never;
+    };
+};
+type Paths<Op extends keyof operations> = OmitNeverPaths<FilterPaths<Op>>;
+/**
+ * Open-fetch client restricted to the route that corresponds to operation {@link Op}
+ */
+export type FetchClient<Op extends keyof operations> = ReturnType<typeof createClient<Paths<Op>>>;
+/**
+ * Type alias for the type of the response body (the "data" field of
+ * {@link FetchResponse<T>}) when that response is successful.
+ */
+export type FetchResponseSuccessData<T> = Required<FetchResponse<T>>["data"];
+/**
+ * Error response type, thrown on non-successful responses.
+ */
+export declare class ErrResponse extends Error {
+    /** Operation that produced this error */
+    readonly operation?: keyof operations;
+    /** HTTP status code text (derived from `this.status`) */
+    readonly statusText?: string;
+    /** HTTP status code */
+    readonly status?: number;
+    /** HTTP response url */
+    readonly url?: string;
+    /**
+     * @param {Partial<ErrResponse>} init Initializer
+     */
+    constructor(init: Partial<ErrResponse>);
+}
+/**
+ * Wrapper around an open-fetch client restricted to a single operation.
+ * The restriction applies only when type checking, the actual
+ * client does not restrict anything at runtime.
+ * client does not restrict anything at runtime
+ */
+export declare class OpClient<Op extends keyof operations> {
+    #private;
+    /**
+     * @param {Op} op The operation this client should be restricted to
+     * @param {FetchClient<Op> | Client} client open-fetch client (either restricted to {@link Op} or not)
+     * @param {EventEmitter} eventEmitter The client-local event dispatcher.
+     */
+    constructor(op: Op, client: FetchClient<Op> | Client, eventEmitter: EventEmitter);
+    /** The operation this client is restricted to */
+    get op(): Op;
+    /**
+     * Inspects the response and returns the response body if the request was successful.
+     * Otherwise, dispatches the error to event listeners, then throws {@link ErrResponse}.
+     *
+     * @param {FetchResponse<T>} resp The response to check
+     * @return {FetchResponseSuccessData<T>} The response data corresponding to response type {@link T}.
+     */
+    private assertOk;
+    /**
+     * Invoke HTTP GET
+     */
+    get(url: PathsWith<Paths<Op>, "get">, init: FetchOptions<FilterKeys<Paths<Op>[PathsWith<Paths<Op>, "get">], "get">>): Promise<("get" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">] & "get"] : unknown) extends infer T ? T extends ("get" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "get">] & "get"] : unknown) ? T extends {
+        responses: any;
+    } ? NonNullable<FilterKeys<import("openapi-fetch").Success<T["responses"]>, `${string}/${string}`>> : unknown : never : never>;
+    /** Invoke HTTP POST */
+    post(url: PathsWith<Paths<Op>, "post">, init: FetchOptions<FilterKeys<Paths<Op>[PathsWith<Paths<Op>, "post">], "post">>): Promise<("post" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">] & "post"] : unknown) extends infer T ? T extends ("post" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "post">] & "post"] : unknown) ? T extends {
+        responses: any;
+    } ? NonNullable<FilterKeys<import("openapi-fetch").Success<T["responses"]>, `${string}/${string}`>> : unknown : never : never>;
+    /** Invoke HTTP PATCH */
+    patch(url: PathsWith<Paths<Op>, "patch">, init: FetchOptions<FilterKeys<Paths<Op>[PathsWith<Paths<Op>, "patch">], "patch">>): Promise<("patch" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">] & "patch"] : unknown) extends infer T ? T extends ("patch" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "patch">] & "patch"] : unknown) ? T extends {
+        responses: any;
+    } ? NonNullable<FilterKeys<import("openapi-fetch").Success<T["responses"]>, `${string}/${string}`>> : unknown : never : never>;
+    /** Invoke HTTP DELETE */
+    del(url: PathsWith<Paths<Op>, "delete">, init: FetchOptions<FilterKeys<Paths<Op>[PathsWith<Paths<Op>, "delete">], "delete">>): Promise<("delete" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">] & "delete"] : unknown) extends infer T ? T extends ("delete" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "delete">] & "delete"] : unknown) ? T extends {
+        responses: any;
+    } ? NonNullable<FilterKeys<import("openapi-fetch").Success<T["responses"]>, `${string}/${string}`>> : unknown : never : never>;
+    /** Invoke HTTP PUT */
+    put(url: PathsWith<Paths<Op>, "put">, init: FetchOptions<FilterKeys<Paths<Op>[PathsWith<Paths<Op>, "put">], "put">>): Promise<("put" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">] & "put"] : unknown) extends infer T ? T extends ("put" extends keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">] ? OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">][keyof OmitNeverPaths<FilterPaths<Op>>[PathsWith<OmitNeverPaths<FilterPaths<Op>>, "put">] & "put"] : unknown) ? T extends {
+        responses: any;
+    } ? NonNullable<FilterKeys<import("openapi-fetch").Success<T["responses"]>, `${string}/${string}`>> : unknown : never : never>;
+}
 /**
  * Creates a new HTTP client, setting the "User-Agent" header to this package's {name}@{version}.
  *
@@ -44,6 +135,14 @@ export declare class CubeSignerApi {
     withOrg(orgId?: string): CubeSignerApi;
     /** Org id or name */
     get orgId(): string;
+    /**
+     * HTTP client restricted to a single operation. The restriction applies only
+     * when type checking, the actual client does not restrict anything at runtime.
+     *
+     * @param {Op} op The operation to restrict the client to
+     * @return {Promise<OpClient<Op>>} The client restricted to {@link op}
+     */
+    private client;
     /**
      * Obtain information about the current user.
      *
@@ -53,14 +152,14 @@ export declare class CubeSignerApi {
     /**
      * Creates a request to change user's TOTP. Returns a {@link TotpChallenge}
      * that must be answered either by calling {@link TotpChallenge.answer} (or
-     * {@link CubeSignerApi.userResetTotpComplete}).
+     * {@link CubeSignerApi.userTotpResetComplete}).
      *
      * @param {string} issuer Optional issuer; defaults to "Cubist"
      * @param {MfaReceipt} mfaReceipt MFA receipt to include in HTTP headers
      */
-    userResetTotpInit(issuer?: string, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<TotpChallenge>>;
+    userTotpResetInit(issuer?: string, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<TotpChallenge>>;
     /**
-     * Answer the TOTP challenge issued by {@link userResetTotpInit}. If successful, user's
+     * Answer the TOTP challenge issued by {@link userTotpResetInit}. If successful, user's
      * TOTP configuration will be updated to that of the TOTP challenge.
      *
      * Instead of calling this method directly, prefer {@link TotpChallenge.answer}.
@@ -68,26 +167,34 @@ export declare class CubeSignerApi {
      * @param {string} totpId - The ID of the TOTP challenge
      * @param {string} code - The TOTP code that should verify against the TOTP configuration from the challenge.
      */
-    userResetTotpComplete(totpId: string, code: string): Promise<void>;
+    userTotpResetComplete(totpId: string, code: string): Promise<void>;
     /**
      * Verifies a given TOTP code against the current user's TOTP configuration.
      * Throws an error if the verification fails.
      *
      * @param {string} code Current TOTP code
      */
-    userVerifyTotp(code: string): Promise<void>;
+    userTotpVerify(code: string): Promise<void>;
+    /**
+     * Delete TOTP from the user's account.
+     * Allowed only if at least one FIDO key is registered with the user's account.
+     * MFA via FIDO is always required.
+     *
+     * @param {MfaReceipt} mfaReceipt Optional MFA receipt to include in HTTP headers
+     */
+    userTotpDelete(mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<Empty>>;
     /**
      * Initiate adding a new FIDO device. MFA may be required.  This returns a {@link AddFidoChallenge}
-     * that must be answered with {@link AddFidoChallenge.answer} or {@link userRegisterFidoComplete}
+     * that must be answered with {@link AddFidoChallenge.answer} or {@link userFidoRegisterComplete}
      * (after MFA approvals).
      *
      * @param {string} name The name of the new device.
      * @param {MfaReceipt} mfaReceipt Optional MFA receipt to include in HTTP headers
      * @return {Promise<CubeSignerResponse<AddFidoChallenge>>} A challenge that must be answered in order to complete FIDO registration.
      */
-    userRegisterFidoInit(name: string, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<AddFidoChallenge>>;
+    userFidoRegisterInit(name: string, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<AddFidoChallenge>>;
     /**
-     * Complete a previously initiated (via {@link userRegisterFidoInit}) request to add a new FIDO device.
+     * Complete a previously initiated (via {@link userFidoRegisterInit}) request to add a new FIDO device.
      *
      * Instead of calling this method directly, prefer {@link AddFidoChallenge.answer} or
      * {@link AddFidoChallenge.createCredentialAndAnswer}.
@@ -95,7 +202,16 @@ export declare class CubeSignerApi {
      * @param {string} challengeId The ID of the challenge returned by the remote end.
      * @param {PublicKeyCredential} credential The answer to the challenge.
      */
-    userRegisterFidoComplete(challengeId: string, credential: PublicKeyCredential): Promise<void>;
+    userFidoRegisterComplete(challengeId: string, credential: PublicKeyCredential): Promise<void>;
+    /**
+     * Delete a FIDO key from the user's account.
+     * Allowed only if TOTP is also defined.
+     * MFA via TOTP is always required.
+     *
+     * @param {string} fidoId The ID of the desired FIDO key
+     * @param {MfaReceipt} mfaReceipt Optional MFA receipt to include in HTTP headers
+     */
+    userFidoDelete(fidoId: string, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<Empty>>;
     /**
      * Obtain information about the current organization.
      * @return {OrgInfo} Information about the organization.
@@ -255,6 +371,15 @@ export declare class CubeSignerApi {
      * @return {Paginator<ListRoleUsersResponse, UserInRoleInfo>} Paginator for iterating over the users in the role.
      */
     roleUsersList(roleId: string, page?: PageOpts): Paginator<ListRoleUsersResponse, UserInRoleInfo>;
+    /**
+     * Create new user session (management and/or signing)
+     *
+     * @param {string} purpose The purpose of the session
+     * @param {string[]} scopes Session scopes.
+     * @param {SignerSessionLifetime} lifetimes Lifetime settings
+     * @return {Promise<SignerSessionData>} New signer session info.
+     */
+    sessionCreate(purpose: string, scopes: string[], lifetimes?: SignerSessionLifetime): Promise<SignerSessionData>;
     /**
      * Create a new signer session for a given role.
      *
@@ -428,8 +553,6 @@ export declare class CubeSignerApi {
      * @return {Promise<SolanaSignResponse | AcceptedResponse>} The response.
      */
     signSolana(key: Key | string, req: SolanaSignRequest, mfaReceipt?: MfaReceipt): Promise<CubeSignerResponse<SolanaSignResponse>>;
-    /** HTTPS client */
-    private client;
     /**
      * List outstanding user-export requests.
      *
@@ -476,6 +599,13 @@ export declare class OidcClient {
      * @param {string} oidcToken User's OIDC token
      */
     constructor(env: EnvInterface, orgId: string, oidcToken: string);
+    /**
+     * HTTP client restricted to a single operation.
+     *
+     * @param {Op} op The operation to restrict the client to
+     * @return {OpClient<Op>} The client restricted to {@link op}
+     */
+    private client;
     /**
      * Exchange an OIDC token for a CubeSigner session token.
      * @param {List<string>} scopes The scopes for the new session