@cubist-labs/cubesigner-sdk 0.4.227 → 0.4.229

package/src/client/api_client.ts

@@ -63,6 +63,10 @@ import type {
   AuditLogRequest,
   AuditLogResponse,
   AuditLogEntry,
+  RoleInfoJwt,
+  KeyAttestationQuery,
+  RoleAttestationQuery,
+  ErrorResponse,
 } from "../schema_types";
 import { encodeToBase64 } from "../util";
 import {
@@ -79,80 +83,85 @@ import { Page, Paginator } from "../paginator";
 import type { KeyPolicy } from "../role";
 import { loadSubtleCrypto } from "../user_export";
 import type * as policy from "../policy";
-import type {
-  AddIdentityRequest,
-  AvaChain,
-  EnvInterface,
-  EotsCreateNonceRequest,
-  EotsCreateNonceResponse,
-  EotsSignRequest,
-  EotsSignResponse,
-  JrpcResponse,
-  JsonArray,
-  ListIdentityResponse,
-  ListKeyRolesResponse,
-  ListKeysResponse,
-  ListRoleKeysResponse,
-  ListRoleUsersResponse,
-  ListRolesResponse,
-  MmiJrpcMethod,
-  PendingMessageInfo,
-  PendingMessageSignResponse,
-  RatchetConfig,
-  Scope,
-  SessionData,
-  SessionLifetime,
-  SessionsResponse,
-  TaprootSignRequest,
-  TaprootSignResponse,
-  BabylonRegistrationRequest,
-  BabylonRegistrationResponse,
-  BabylonStakingRequest,
-  BabylonStakingResponse,
-  UpdateUserMembershipRequest,
-  HistoricalTx,
-  ListHistoricalTxResponse,
-  PublicOrgInfo,
-  ImportDeriveKeyProperties,
-  PasswordResetRequest,
-  EmailOtpResponse,
-  AuthenticationRequest,
-  AuthenticationResponse,
-  CreateKeyProperties,
-  InvitationAcceptRequest,
-  MfaReceipts,
-  SuiSignRequest,
-  SuiSignResponse,
-  QueryMetricsRequest,
-  QueryMetricsResponse,
-  CreateOrgRequest,
-  KeyTypeAndDerivationPath,
-  DeriveMultipleKeyTypesProperties,
-  ContactInfo,
-  ListContactsResponse,
-  JsonValue,
-  EditPolicy,
-  UpdateContactRequest,
-  AddressMap,
-  RolePolicy,
-  InvokePolicyResponse,
-  InvokePolicyRequest,
-  UploadWasmPolicyRequest,
-  UploadWasmPolicyResponse,
-  LoginRequest,
-  PasskeyAssertAnswer,
-  schemas,
-  KeyWithPoliciesInfo,
-  GetRoleKeyOptions,
-  GetUserByEmailResponse,
-  GetUserByOidcResponse,
-  EmailTemplatePurpose,
+import {
+  type AddIdentityRequest,
+  type AvaChain,
+  type EnvInterface,
+  type EotsCreateNonceRequest,
+  type EotsCreateNonceResponse,
+  type EotsSignRequest,
+  type EotsSignResponse,
+  type JrpcResponse,
+  type JsonArray,
+  type ListIdentityResponse,
+  type ListKeyRolesResponse,
+  type ListKeysResponse,
+  type ListRoleKeysResponse,
+  type ListRoleUsersResponse,
+  type ListRolesResponse,
+  type MmiJrpcMethod,
+  type PendingMessageInfo,
+  type PendingMessageSignResponse,
+  type RatchetConfig,
+  type Scope,
+  type SessionData,
+  type SessionLifetime,
+  type SessionsResponse,
+  type TaprootSignRequest,
+  type TaprootSignResponse,
+  type BabylonRegistrationRequest,
+  type BabylonRegistrationResponse,
+  type BabylonStakingRequest,
+  type BabylonStakingResponse,
+  type UpdateUserMembershipRequest,
+  type HistoricalTx,
+  type ListHistoricalTxResponse,
+  type PublicOrgInfo,
+  type ImportDeriveKeyProperties,
+  type PasswordResetRequest,
+  type EmailOtpResponse,
+  type AuthenticationRequest,
+  type AuthenticationResponse,
+  type CreateKeyProperties,
+  type InvitationAcceptRequest,
+  type MfaReceipts,
+  type SuiSignRequest,
+  type SuiSignResponse,
+  type QueryMetricsRequest,
+  type QueryMetricsResponse,
+  type CreateOrgRequest,
+  type KeyTypeAndDerivationPath,
+  type DeriveMultipleKeyTypesProperties,
+  type ContactInfo,
+  type ListContactsResponse,
+  type JsonValue,
+  type EditPolicy,
+  type UpdateContactRequest,
+  type AddressMap,
+  type RolePolicy,
+  type InvokePolicyResponse,
+  type InvokePolicyRequest,
+  type UploadWasmPolicyRequest,
+  type UploadWasmPolicyResponse,
+  type LoginRequest,
+  type PasskeyAssertAnswer,
+  type schemas,
+  type KeyWithPoliciesInfo,
+  type GetRoleKeyOptions,
+  type GetUserByEmailResponse,
+  type GetUserByOidcResponse,
+  type EmailTemplatePurpose,
+  ErrResponse,
 } from "../index";
 import { assertOk, op, type Op, type Operation, apiFetch } from "../fetch";
 import { 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";
+
 /**
  * String returned by API when a user does not have an email address (for backwards compatibility)
  */
@@ -817,12 +826,17 @@ export class ApiClient extends BaseClient {
    * The response is a JWT whose claims are the properties of the requested key.
    *
    * @param keyId The id of the key.
-   * @returns A JWT whose claims are the properties of the key.
+   * @param query Query parameters:
+   * @param query.include_roles if specified, include all the roles the key is in.
+   * @returns A JWT whose claims are the properties of the key. The type of the returned JWT payload is {@link KeyAttestationClaims}.
    */
-  async keyAttest(keyId: string): Promise<KeyInfoJwt> {
+  async keyAttest(keyId: string, query?: KeyAttestationQuery): Promise<KeyInfoJwt> {
     const o = op("/v0/org/{org_id}/keys/{key_id}/attest", "get");
     return this.exec(o, {
-      params: { path: { key_id: keyId } },
+      params: {
+        path: { key_id: keyId },
+        query,
+      },
     });
   }
 
@@ -1184,7 +1198,7 @@ export class ApiClient extends BaseClient {
 
   // #endregion
 
-  // #region ROLES: roleCreate, roleRead, roleUpdate, roleDelete, rolesList
+  // #region ROLES: roleCreate, roleGet, roleAttest, roleRead, roleUpdate, roleDelete, rolesList
 
   /**
    * Create a new role.
@@ -1216,6 +1230,27 @@ export class ApiClient extends BaseClient {
     });
   }
 
+  /**
+   * Attest to role properties.
+   *
+   * The response is a JWT whose claims are the properties of the requested role.
+   *
+   * @param roleId The id of the role.
+   * @param query Query parameters:
+   * @param query.verbosity Role properties to include in an attestation. Defaults to basic role properties, including associated users, but excluding associated keys.
+   * @param query.key_filter Filter down to a single associated key. Defaults to including all associated keys.
+   * @returns A JWT whose claims are the role properties. The type of the returned JWT payload is {@link RoleAttestationClaims}.
+   */
+  async roleAttest(roleId: string, query?: RoleAttestationQuery): Promise<RoleInfoJwt> {
+    const o = op("/v0/org/{org_id}/roles/{role_id}/attest", "get");
+    return this.exec(o, {
+      params: {
+        path: { role_id: roleId },
+        query,
+      },
+    });
+  }
+
   /**
    * Update a role.
    *
@@ -2680,9 +2715,35 @@ export class ApiClient extends BaseClient {
       method: method,
       params: params,
     };
-    const func = async (headers?: HeadersInit) => this.exec(o, { headers, body });
-    const resp = (await CubeSignerResponse.create(this.env, func)).data();
-    return resp;
+    const func = async (headers?: HeadersInit) => {
+      const resp = await this.exec(o, { headers, body });
+      if (resp.error) {
+        const data = resp.error.data as ErrorResponse | undefined;
+        throw new ErrResponse({
+          message: resp.error.message,
+          errorCode: data?.error_code,
+          requestId: data?.request_id,
+        });
+      }
+      return resp;
+    };
+    const resp = await CubeSignerResponse.create(this.env, func);
+    return resp.data();
+  }
+
+  /**
+   * Retrieve a proof of this session's CubeSigner identity.
+   *
+   * @returns a JWT that can be validated against the JWKS from {@link customerProofJwksUrl}.
+   */
+  async getCustomerProof(): Promise<string> {
+    const resp = await this.mmi("custodian_getCustomerProof", []);
+    const jwt = resp.result?.jwt;
+    if (!jwt || typeof jwt !== "string") {
+      console.warn("Unexpected getCustomerProof response", resp);
+      throw new Error("The type JWT included in the customer proof response is not string");
+    }
+    return jwt;
   }
 
   /**
@@ -2728,6 +2789,24 @@ export class ApiClient extends BaseClient {
     return await this.exec(o, { params: { path: { msg_id: msgId } } });
   }
 
+  /**
+   * @returns JSON Web Key Set (JWKS) URL with the keys used for key/role attestations (see {@link keyAttest} and {@link roleAttest}).
+   */
+  attestationJwksUrl(): URL {
+    const url = "/v0/attestation/.well-known/jwks.json";
+    op(url, "get"); // just to type check the url above
+    return new URL(`${this.env.SignerApiRoot.replace(/\/$/, "")}${url}`);
+  }
+
+  /**
+   * @returns JSON Web Key Set (JWKS) URL with the keys used for validating JWTs returned by the {@link customerProof} method.
+   */
+  customerProofJwksUrl(): URL {
+    const url = "/v0/mmi/v3/.well-known/jwks.json";
+    op(url, "get"); // just to type check the url above
+    return new URL(`${this.env.SignerApiRoot.replace(/\/$/, "")}${url}`);
+  }
+
   // #endregion
 
   /**
@@ -2748,7 +2827,7 @@ export class ApiClient extends BaseClient {
   }
 
   /**
-   * Returns a JSON Web Key Set (JWKS) with the keys used for key attestations (see {@link keyAttest}).
+   * Returns a JSON Web Key Set (JWKS) with the keys used for key attestations (see {@link keyAttest} and {@link roleAttest}).
    *
    * @param env The CubeSigner environment
    * @returns A JWKS with they keys used for key attestation.

package/src/key.ts

@@ -28,6 +28,7 @@ import type {
   DiffieHellmanRequest,
   DiffieHellmanResponse,
   KeyInfoJwt,
+  KeyAttestationQuery,
 } from "./schema_types";
 import type {
   ApiClient,
@@ -51,6 +52,10 @@ import { CubeSignerClient, delay } from ".";
 import { loadSubtleCrypto } from "./user_export";
 import { encodeToHex, encodeToBase64 } from "./util";
 
+// these types are used in doc comments only
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { KeyAttestationClaims } from "./schema_types";
+
 /** Secp256k1 key type */
 export enum Secp256k1 {
   Evm = "SecpEthAddr",
@@ -165,10 +170,12 @@ export class Key {
   /**
    * Attest to key properties.
    *
-   * @returns A JWT whose claims are the key properties.
+   * @param query Query parameters:
+   * @param query.include_roles If specified, include all the roles the key is in.
+   * @returns A JWT whose claims are the properties of the key. The type of the returned JWT payload is {@link KeyAttestationClaims}.
    */
-  async attest(): Promise<KeyInfoJwt> {
-    return await this.#apiClient.keyAttest(this.id);
+  async attest(query?: KeyAttestationQuery): Promise<KeyInfoJwt> {
+    return await this.#apiClient.keyAttest(this.id, query);
   }
 
   /** @returns The type of key. */

package/src/role.ts

@@ -19,9 +19,14 @@ import type {
   GetRoleKeyOptions,
   EditPolicy,
   MfaPolicy,
+  RoleInfoJwt,
 } from ".";
 import { Key, SignerSessionInfo } from ".";
 
+// these types are used in doc comments only
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { RoleAttestationClaims, RoleAttestationQuery } from "./schema_types";
+
 type NameOrAddressOrNull = string | null;
 
 /**
@@ -610,6 +615,18 @@ export class Role {
     return this.#data;
   }
 
+  /**
+   * Attest to role properties.
+   *
+   * @param query Query parameters:
+   * @param query.verbosity Role properties to include in an attestation. Defaults to basic role properties, including associated users, but excluding associated keys.
+   * @param query.key_filter Filter down to a single associated key. Defaults to including all associated keys.
+   * @returns A JWT whose claims are the role properties. The type of the returned JWT payload is {@link RoleAttestationClaims}.
+   */
+  async attest(query?: RoleAttestationQuery): Promise<RoleInfoJwt> {
+    return await this.#apiClient.roleAttest(this.id, query);
+  }
+
   /**
    * Delete the role.
    *

package/src/schema.ts

@@ -1129,6 +1129,15 @@ export interface paths {
      */
     put: operations["addUserToRole"];
   };
+  "/v0/org/{org_id}/roles/{role_id}/attest": {
+    /**
+     * Attest to Role Properties
+     * @description Attest to Role Properties
+     *
+     * The response is a JWT whose claims are the requested role properties.
+     */
+    get: operations["attestRole"];
+  };
   "/v0/org/{org_id}/roles/{role_id}/keys": {
     /**
      * List Role Keys
@@ -2923,6 +2932,7 @@ export interface components {
       | "ResetMemberMfa"
       | "CompleteResetMemberMfa"
       | "CreateRole"
+      | "AttestRole"
       | "GetRole"
       | "ListTokenKeys"
       | "ListRoles"
@@ -4614,6 +4624,7 @@ export interface components {
       | "manage:role:create"
       | "manage:role:delete"
       | "manage:role:get:*"
+      | "manage:role:attest"
       | "manage:role:get:keys"
       | "manage:role:get:keys:list"
       | "manage:role:get:keys:get"
@@ -5320,6 +5331,13 @@ export interface components {
       /** @description The keys included in this set */
       keys: Record<string, never>[];
     };
+    KeyAttestationClaims: {
+      exp: components["schemas"]["EpochDateTime"];
+      iat: components["schemas"]["EpochDateTime"];
+      key_info: components["schemas"]["KeyInfo"];
+      /** @description If requested, the roles the key is currently in. */
+      key_roles?: components["schemas"]["KeyInRoleInfo"][] | null;
+    };
     KeyCountDimensions: {
       /** @description The key type */
       key_type: string;
@@ -7552,13 +7570,32 @@ export interface components {
      * @enum {string}
      */
     RoleAction: "CreateToken" | "GetKey";
+    RoleAttestationClaims: {
+      exp: components["schemas"]["EpochDateTime"];
+      iat: components["schemas"]["EpochDateTime"];
+      query: components["schemas"]["RoleAttestationQuery"];
+      role_info: components["schemas"]["RoleInfo"];
+      /** @description The information about the keys currently in this role. */
+      role_keys?: components["schemas"]["KeyInRoleInfo"][] | null;
+      /** @description The IDs of the users who are currently in this role. */
+      role_users: string[];
+    };
+    RoleAttestationQuery: {
+      key_filter?: components["schemas"]["Id"] | null;
+      verbosity?: components["schemas"]["RoleAttestationVerbosity"];
+    };
+    /**
+     * @description Specifies which role properties to include in an attestation
+     * @enum {string}
+     */
+    RoleAttestationVerbosity: "Summary" | "WithKeys" | "Full";
     RoleInfo: components["schemas"]["CommonFields"] & {
       /**
        * @description Whether the role is enabled
        * @example true
        */
       enabled: boolean;
-      /** @description Deprecated The CubeSigner IDs of at most 100 keys associated with this role */
+      /** @description Deprecated. The CubeSigner IDs of at most 100 keys associated with this role. */
       keys?: components["schemas"]["KeyInRoleInfo"][] | null;
       /**
        * @description Whether the current user is a member of the role. This is always true,
@@ -7595,6 +7632,11 @@ export interface components {
       /** @description Deprecated. The list of at most 100 users with access to the role. */
       users?: string[] | null;
     };
+    /** @description Response returned when requesting a role attestation. */
+    RoleInfoJwt: {
+      /** @description A JSON Web Token whose claims contain the `RoleInfo` structure. */
+      jwt: string;
+    };
     /** @description All scopes for accessing CubeSigner APIs */
     Scope: components["schemas"]["ExplicitScope"] | string;
     /** @description A set of scopes. */
@@ -10326,7 +10368,7 @@ export interface components {
            * @example true
            */
           enabled: boolean;
-          /** @description Deprecated The CubeSigner IDs of at most 100 keys associated with this role */
+          /** @description Deprecated. The CubeSigner IDs of at most 100 keys associated with this role. */
           keys?: components["schemas"]["KeyInRoleInfo"][] | null;
           /**
            * @description Whether the current user is a member of the role. This is always true,
@@ -10365,6 +10407,15 @@ export interface components {
         };
       };
     };
+    /** @description Response returned when requesting a role attestation. */
+    RoleInfoJwt: {
+      content: {
+        "application/json": {
+          /** @description A JSON Web Token whose claims contain the `RoleInfo` structure. */
+          jwt: string;
+        };
+      };
+    };
     SessionInfo: {
       content: {
         "application/json": components["schemas"]["SessionMetadata"] & {
@@ -12780,6 +12831,9 @@ export interface operations {
    */
   attestKey: {
     parameters: {
+      query?: {
+        include_roles?: boolean | null;
+      };
       path: {
         /**
          * @description Name or ID of the desired Org
@@ -14234,6 +14288,9 @@ export interface operations {
    */
   getRole: {
     parameters: {
+      query?: {
+        summarize?: boolean | null;
+      };
       path: {
         /**
          * @description Name or ID of the desired Org
@@ -14440,6 +14497,48 @@ export interface operations {
       };
     };
   };
+  /**
+   * Attest to Role Properties
+   * @description Attest to Role Properties
+   *
+   * The response is a JWT whose claims are the requested role properties.
+   */
+  attestRole: {
+    parameters: {
+      query?: {
+        /**
+         * @description Role properties to include in an attestation. Defaults to basic role
+         * properties, including associated users, but excluding associated keys.
+         */
+        verbosity?: components["schemas"]["RoleAttestationVerbosity"];
+        /**
+         * @description Associated keys filter, i.e., when specified, out all other associated
+         * keys are filtered out. Defaults to including all associated keys.
+         */
+        key_filter?: components["schemas"]["Id"] | null;
+      };
+      path: {
+        /**
+         * @description Name or ID of the desired Org
+         * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        org_id: string;
+        /**
+         * @description Name or ID of the desired Role
+         * @example Role#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        role_id: string;
+      };
+    };
+    responses: {
+      200: components["responses"]["RoleInfoJwt"];
+      default: {
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
+    };
+  };
   /**
    * List Role Keys
    * @description List Role Keys

package/src/schema_types.ts

@@ -1,4 +1,4 @@
-import type { components, operations } from "./schema";
+import type { components, operations, paths } from "./schema";
 import type { JsonMap, JsonValue } from "./util";
 
 export type schemas = components["schemas"];
@@ -81,6 +81,14 @@ export type KeyProperties = schemas["CreateAndUpdateKeyProperties"];
 export type CreateKeyRequest = schemas["CreateKeyRequest"];
 export type KeyInfo = schemas["KeyInfo"];
 export type KeyInfoJwt = schemas["KeyInfoJwt"];
+export type KeyAttestationClaims = schemas["KeyAttestationClaims"];
+export type KeyAttestationQuery =
+  paths["/v0/org/{org_id}/keys/{key_id}/attest"]["get"]["parameters"]["query"];
+export type RoleInfoJwt = schemas["RoleInfoJwt"];
+export type RoleAttestationClaims = schemas["RoleAttestationClaims"];
+export type RoleAttestationQuery =
+  paths["/v0/org/{org_id}/roles/{role_id}/attest"]["get"]["parameters"]["query"];
+export type RoleAttestationVerbosity = schemas["RoleAttestationVerbosity"];
 export type KeyInRoleInfo = schemas["KeyInRoleInfo"];
 export type GetUsersInOrgResponse = schemas["PaginatedGetUsersInOrgResponse"];
 export type GetUserByEmailResponse = schemas["GetUserByEmailResponse"];

package/src/scopes.ts

@@ -129,6 +129,7 @@ export const AllScopes: Record<ExplicitScope, string> =
   "manage:policy:createImportKey"               : "Allows access only to the policy key endpoint",
   "manage:role:*"                               : "Allows access to all role endpoints",
   "manage:role:readonly"                        : "Allows access to all role readonly endpoints",
+  "manage:role:attest"                          : "Allows access only to the role 'attest' endpoint",
   "manage:role:create"                          : "Allows access only to the role 'create' endpoint",
   "manage:role:delete"                          : "Allows access only to the role 'delete' endpoint",
   "manage:role:get:*"                           : "Allows access only to the role 'get' endpoint",