import type { ApiClient, ContractAddress, EvmTxCmp, SolanaTxCmp, KeyWithPoliciesInfo, PageOpts, RoleInfo, Scope, SessionData, SessionLifetime, BabylonStakingRequest, OperationKind, MfaReceipts, CubeSignerResponse, Empty, RestrictedActionsMap, GetRoleKeyOptions, EditPolicy, MfaPolicy, RoleInfoJwt } from "./index.ts"; import { Key, SignerSessionInfo } from "./index.ts"; import type { RoleAttestationQuery } from "./schema_types.ts"; type NameOrAddressOrNull = string | null; /** Only allow the following operations */ export type OperationAllowlist = { OperationAllowlist: OperationKind[]; }; /** * Restrict the receiver for EVM transactions. * * @example { TxReceiver: "0x8c594691c0e592ffa21f153a16ae41db5befcaaa" } * @example { TxReceiver: null } * @example { TxReceiver: [null, "0x8c594691c0e592ffa21f153a16ae41db5befcaaa"] } */ export type TxReceiver = { TxReceiver: NameOrAddressOrNull | NameOrAddressOrNull[]; }; /** * Restrict the receiver for SUI transactions. * * @example { SuiTxReceiver: [ "0xc9837a0ad2d11468bbf847e3af4e3ede837bcc02a1be6faee621df1a8a403cbf" ] } */ export type SuiTxReceivers = { SuiTxReceivers: string[]; }; /** * Restrict the receiver for BTC transactions. * * @example { BtcTxReceivers: [ "bc1q3qdavl37dnj6hjuazdzdxk0aanwjsg44mguq66", "bc1qfrjtxm8g20g97qzgadg7v9s3ftjkq02qfssk87" ] } */ export type BtcTxReceivers = { BtcTxReceivers: string[]; }; /** The kind of deposit contracts. */ export declare enum DepositContract { /** Canonical deposit contract */ Canonical = 0, /** Wrapper deposit contract */ Wrapper = 1 } /** Restrict transactions to calls to deposit contract. */ export type TxDeposit = TxDepositBase | TxDepositPubkey | TxDepositRole; /** Restrict transactions to calls to deposit contract*/ export type TxDepositBase = { TxDeposit: { kind: DepositContract; }; }; /** * Restrict transactions to calls to deposit contract with fixed validator (pubkey): * * @example { TxDeposit: { kind: DespositContract.Canonical, validator: { pubkey: "8879...8"} }} */ export type TxDepositPubkey = { TxDeposit: { kind: DepositContract; pubkey: string; }; }; /** * Restrict transactions to calls to deposit contract with any validator key in a role: * * @example { TxDeposit: { kind: DespositContract.Canonical, validator: { role_id: "Role#c63...af"} }} */ export type TxDepositRole = { TxDeposit: { kind: DepositContract; role_id: string; }; }; /** * Restrict transaction values to amounts at or below the given limit in wei. * Currently, this only applies to EVM transactions. */ export type TxValueLimit = TxValueLimitPerTx | TxValueLimitWindow; /** * Restrict individual transaction values to amounts at or below the given limit in wei. * Currently, this only applies to EVM transactions. * * @example { TxValueLimit: "0x12A05F200" } */ export type TxValueLimitPerTx = { TxValueLimit: string; }; /** * Restrict transaction values, in wei, over a time window. * Currently, this only applies to EVM transactions. * * @example { TxValueLimit: { limit: "0x12A05F200", window: 86400 }} * @example { TxValueLimit: { limit: "0x12A05F200", window: 604800, chain_ids: [ "1", "5" ] }} * @example { TxValueLimit: { limit: "0x12A05F200", window: 604800, except_chain_ids: [ "1" ] }} */ export type TxValueLimitWindow = { TxValueLimit: { /** * Max allowed value in wei */ limit: string; /** * Optional sliding time window (in seconds). * * If specified, the `limit` applies to the aggregate value of all transactions within that * time window; otherwise, the window is 0, i.e., the limit applies to individual transactions. */ window?: number; /** * Optional chain ids. * * If specified, the policy applies only if a transaction is on one of the * given chains (otherwise it applies to all transactions). If a 'window' is * also defined, the policy limit applies cumulatively across all specified chains. * * Must not be specified together with `except_chain_ids`. */ chain_ids?: string[]; /** * Optional chain ids to exclude. * * If specified, the policy applies only if a transaction is on a chain id not * included in this list. If a 'window' is also defined, the policy limit applies * cumulatively across all chains other than the listed ones. * * Must not be specified together with `chain_ids`. */ except_chain_ids?: string[]; }; }; /** * Restrict transaction max gas costs to amounts at or below the given limit in wei. * * @example { TxGasCostLimit: "0x27CA57357C000" } */ export type TxGasCostLimit = { TxGasCostLimit: string; }; /** * Restrict ERC-20 method calls according to the {@link Erc20Policy}. * Only applies to EVM transactions that call a valid ERC-20 method. * Non-ERC-20 transactions are ignored by this policy. * * @example { IfErc20Tx: { transfer_limits: [{ limit: "0xE8D4A51000" }] } } * @example { IfErc20Tx: { allowed_contracts: [ { address: "0x0000000000000000000000034a20b809008afeb0", "chain_id": "1" } ] } } */ export type IfErc20Tx = { IfErc20Tx: Erc20Policy; }; /** * Restrict transactions to only allow valid ERC-20 method calls. */ export type AssertErc20Tx = "AssertErc20Tx"; /** * Restrict transactions to only allow native token transfers. */ export type AssertTransferOnlyTx = "AssertTransferOnlyTx"; /** * Restrict ERC-20 `transfer` and `transferFrom` transaction values and receivers. * Only applies to contracts defined in `applies_to_contracts`, * or to all contracts if not defined. * The limit is in the token's unit. */ export type Erc20TransferLimit = { limit?: string; receivers?: string[]; applies_to_contracts?: ContractAddress[]; }; /** * Restrict ERC-20 `approve` transaction values and spenders. * Only applies to contracts defined in `applies_to_contracts`, * or to all contracts if not defined. * The limit is in the token's unit. */ export type Erc20ApproveLimit = { limit?: string; spenders?: string[]; applies_to_contracts?: ContractAddress[]; }; /** * Restricts ERC-20 policies to a set of known contracts, * and can define limits on `transfer`, `transferFrom` and `approve` method calls. */ export type Erc20Policy = { allowed_contracts?: ContractAddress[]; transfer_limits?: Erc20TransferLimit[]; approve_limits?: Erc20ApproveLimit[]; }; /** * Restrict transactions to only allow calling the given methods in the given contracts. * * @example { AssertContractTx: { * allowlist: [{ * address: { address: "0x0000000000000000000000034a20b809008afeb0", "chain_id": "1" }, * methods: [ * "function name() public view returns (string)", * "function transfer(address to, uint256 value) public returns (bool success)" * ] * }] * } */ export type AssertContractTx = { AssertContractTx: { allowlist: { address: ContractAddress; methods: string[]; }[]; }; }; /** * Solana address matcher. * Can be either the pubkey of the account using base58 encoding, * or the index of the pubkey of an address lookup table and the * index of the account in that table. */ export type SolanaAddressMatcher = string | { alt_address: string; index: number; }; /** * Solana instruction matcher. */ export type SolanaInstructionMatcher = { program_id: string; index?: number; accounts?: ({ address: SolanaAddressMatcher | SolanaAddressMatcher[]; } | ({ /** @deprecated use `address` instead. */ pubkey: string; } & { index: number; }))[]; data?: string | { data: string; start_index: number; }[]; }; /** * Restricts Solana transaction instructions. Can limit the number of instructions, * the list of allowed instructions, and a set of required instructions in all transactions. */ export type SolanaInstructionPolicy = { SolanaInstructionPolicy: { count?: { min?: number; max?: number; }; allowlist?: SolanaInstructionMatcher[]; required?: SolanaInstructionMatcher[]; }; }; /** * Restrict the total value transferred out of the inputs in a Bitcoin Segwit transaction * to amounts at or below the given limit. */ export type BtcSegwitValueLimit = BtcSegwitValueLimitPerTx | BtcSegwitValueLimitWindow; /** * Restrict individual Bitcoin Segwit transaction values to amounts at or below * the given limit. * * @example { BtcSegwitValueLimit: "1000000" } */ export type BtcSegwitValueLimitPerTx = { BtcSegwitValueLimit: number; }; /** * Restrict the total value transferred out of the inputs in Bitcoin Segwit transactions * over a time window. * * @example { BtcSegwitValueLimit: { limit: "1000000", window: 86400 }} */ export type BtcSegwitValueLimitWindow = { BtcSegwitValueLimit: { limit: number; window?: number; }; }; /** * Only allow connections from clients whose IP addresses match any of these IPv4 CIDR blocks. * * @example { SourceIpAllowlist: [ "123.456.78.9/16" ] } */ export type SourceIpAllowlist = { SourceIpAllowlist: string[]; }; /** * Disallow signing until the specified Unix timestamp (in seconds since epoch). * * @example { TimeLock: 1750000000 } */ export type TimeLock = { TimeLock: number; }; export type HttpRequestComparer = "Eq" | { EvmTx: EvmTxCmp; } | { SolanaTx: SolanaTxCmp; }; /** * Require MFA for transactions. * * @example { * RequireMfa: { * count: 1, * allowed_mfa_types: [ "Totp" ], * allowed_approvers: [ "User#123" ], * restricted_operations: [ * "Eth1Sign", * "BlobSign" * ] * } * } */ export type RequireMfa = { RequireMfa: MfaPolicy; }; /** * Require that the key is accessed via a role session. * * @example { "RequireRoleSession": "*" } * @example { "RequireRoleSession": [ * "Role#34dfb654-f36d-48ea-bdf6-833c0d94b759", * "Role#98d87633-d1a7-4612-b6b4-b2fa2b43cd3d" * ]} */ export type RequireRoleSession = { /** Require either any role session or any one of the approved roles */ RequireRoleSession: "*" | string[]; }; /** * Forwards the request parameters to this webhook which determines * whether the request is allowed to be executed. */ export type WebhookPolicy = { Webhook: { /** The url of the webhook */ url: string; /** Optional HTTP method to use. Defaults to POST. */ method?: string; /** Optional HTTP headers to set */ headers?: Record; /** * Request execution timeout in seconds; must be at least 1 not exceed 5 seconds. * Defaults to 5. */ timeout?: number; /** * CubeSigner operations to which this policy should apply. * When omitted, applies to all operations. */ restricted_operations?: OperationKind[]; }; }; /** Babylon staking policy */ export type BabylonStaking = { BabylonStaking: { /** * Public keys that can be used for staking. Must be defined if the policy is being applied * to a SegWit key; otherwise, if `undefined`, only the key to which the policy is being * applied can be used as the staking public key when creating Babylon-related transactions. * * Hex-encoded public keys, WITHOUT the leading '0x'. */ allowed_staker_pks?: string[]; /** * Finality providers that can be used for staking. If `undefined`, any finality * provider can be used. * * Hex-encoded public keys, WITHOUT the leading '0x'. */ allowed_finality_provider_pks?: string[]; /** * Change addresses that can be used in staking transactions. If `undefined`, only * the key to which the policy is being applied can be used as the change address. */ allowed_change_addrs?: string[]; /** * Withdrawal addresses that can be used in withdrawal txns. If `undefined`, only * the key to which the policy is being applied can be used as the withdrawal address. */ allowed_withdrawal_addrs?: string[]; /** Babylon networks that this key can be used with. If `undefined`, any network. */ allowed_network_ids?: BabylonStakingRequest["network"][]; /** * Max fee allowed in a staking or withdrawal txn. If `undefined`, there is no fee limit. * Note that the fee for voluntary unbonding and slashing are fixed by the Babylon * params, and this limit is not enforced in those cases. */ max_fee?: number; /** Min staking time in seconds. If `undefined`, uses the limit defined by the Babylon staking params. */ min_lock_time?: number; /** Max staking time in seconds. If `undefined`, uses the limit defined by the Babylon staking params. */ max_lock_time?: number; /** Min staking amount in SAT. If `undefined`, uses the limit defined by the Babylon staking params. */ min_staking_value?: number; /** Max staking amount in SAT. If `undefined`, uses the limit defined by the Babylon staking params. */ max_staking_value?: number; /** Minimum network parameters version allowed. */ min_params_version?: number; /** Maximum network parameters version allowed. */ max_params_version?: number; }; }; /** Allow raw blob signing */ export declare const AllowRawBlobSigning: "AllowRawBlobSigning"; export type AllowRawBlobSigning = typeof AllowRawBlobSigning; /** Allow Diffie-Hellman exchange */ export declare const AllowDiffieHellmanExchange: "AllowDiffieHellmanExchange"; export type AllowDiffieHellmanExchange = typeof AllowDiffieHellmanExchange; /** Allow EIP-191 signing */ export declare const AllowEip191Signing: "AllowEip191Signing"; export type AllowEip191Signing = typeof AllowEip191Signing; /** Allow EIP-712 signing */ export declare const AllowEip712Signing: "AllowEip712Signing"; export type AllowEip712Signing = typeof AllowEip712Signing; /** Allow EIP-7702 signing */ export declare const AllowEip7702Signing: "AllowEip7702Signing"; export type AllowEip7702Signing = typeof AllowEip7702Signing; /** Allow BTC message signing */ export declare const AllowBtcMessageSigning: "AllowBtcMessageSigning"; export type AllowBtcMessageSigning = typeof AllowBtcMessageSigning; /** Allow BTC message signing */ export declare const AllowAutoSign: "AllowAutoSign"; export type AllowAutoSign = typeof AllowAutoSign; export type AllowPolicy = AllowRawBlobSigning | AllowDiffieHellmanExchange | AllowEip191Signing | AllowEip712Signing | AllowEip7702Signing | AllowBtcMessageSigning | AllowAutoSign; /** A reference to an org-level named policy, using its name/id and its version */ export type PolicyReference = `${string}/v${number}` | `${string}/latest`; /** * A reference to an org-level named policy using its id. * We cannot use the policy's name in this format. */ export type NamedPolicyReference = { Reference: PolicyReference; }; /** Explicit "permit" vs "deny" policy outcome, with or without a descriptive message. */ export type Const = ConstOutcome | { outcome: ConstOutcome; message: string; }; /** Explicit "permit" vs "deny" policy outcome. */ export type ConstOutcome = "Permit" | "Deny"; /** * A {@link https://github.com/google/cel-spec Common Expression Language} * policy to evaluate against the following context: * * ```json * { * "operation": OperationKind, * "identity": , * "body": * } * ``` */ export type Cel = { Cel: string; }; /** Key policies that restrict the requests that the signing endpoints accept */ export type KeyDenyPolicy = Const | Cel | OperationAllowlist | TxReceiver | TxDeposit | TxValueLimit | TxGasCostLimit | IfErc20Tx | AssertErc20Tx | AssertTransferOnlyTx | AssertContractTx | SuiTxReceivers | BtcTxReceivers | SourceIpAllowlist | TimeLock | SolanaInstructionPolicy | BtcSegwitValueLimit | RequireMfa | RequireRoleSession | BabylonStaking | WebhookPolicy | PolicyAnd | PolicyOr | PolicyNot | PolicyIte | NamedPolicyReference; /** * Key policy * * @example [ * { * "TxReceiver": "0x8c594691c0e592ffa21f153a16ae41db5befcaaa" * }, * { * "TxDeposit": { * "kind": "Canonical" * } * }, * { * "RequireMfa": { * "count": 1, * "allowed_mfa_types": ["CubeSigner"], * "restricted_operations": [ * "Eth1Sign", * "BlobSign" * ] * } * } * ] * * @example ["AssertErc20Tx", { "IfErc20Tx": "transfer_limits": [ { "limit": "0x3B9ACA00" } ] }] */ export type KeyPolicy = KeyPolicyRule[]; export type KeyPolicyRule = KeyDenyPolicy | AllowPolicy | PolicyReference; /** Role policy */ export type RolePolicy = RolePolicyRule[]; export type RolePolicyRule = KeyDenyPolicy | PolicyReference; /** Conditional policy */ export type Conditional = { /** The condition to evaluate first. */ if: KeyDenyPolicy; /** The policy to apply when the condition evaluates to 'Permit'. */ then: KeyDenyPolicy; }; /** One or more conditional policies */ export type Conditionals = Conditional | { conditionals: Conditional[]; }; /** If-then-else policy */ export type PolicyIte = { IfThenElse: Conditionals & { /** The policy to apply when none of the conditionals apply. */ else: KeyDenyPolicy; }; }; export type PolicyAnd = { And: KeyDenyPolicy[]; }; export type PolicyOr = { Or: KeyDenyPolicy[]; }; export type PolicyNot = { Not: KeyDenyPolicy; }; /** A key guarded by a policy. */ export declare class KeyWithPolicies { #private; readonly roleId: string; readonly keyId: string; /** @returns The cached information */ get cached(): KeyWithPoliciesInfo; /** @returns The cached policy */ get policy(): KeyPolicy | undefined; /** @returns The key */ getKey(): Promise; /** * Constructor. * * @param apiClient The API client to use. * @param keyWithPolicies The key and its policies * @internal */ constructor(apiClient: ApiClient, keyWithPolicies: KeyWithPoliciesInfo); } /** Roles. */ export declare class Role { #private; /** @returns Human-readable name for the role */ get name(): string | undefined; /** * @returns The ID of the role. * * @example Role#bfe3eccb-731e-430d-b1e5-ac1363e6b06b */ get id(): string; /** * @returns the cached properties of this role. The cached properties * reflect the state of the last fetch or update (e.g., after awaiting * `Role.enabled()` or `Role.disable()`). */ get cached(): RoleInfo; /** * 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}. */ attest(query?: RoleAttestationQuery): Promise; /** * Delete the role. * * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided * @returns A response which can be used to approve MFA if needed */ delete(mfaReceipt?: MfaReceipts): Promise>; /** @returns Whether the role is enabled */ enabled(): Promise; /** * Enable the role. * * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided */ enable(mfaReceipt?: MfaReceipts): Promise; /** * Disable the role. * * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided */ disable(mfaReceipt?: MfaReceipts): Promise; /** * Set new policy (overwriting any policies previously set for this role) * * @param policy The new policy to set * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided */ setPolicy(policy: RolePolicy, mfaReceipt?: MfaReceipts): Promise; /** * Append to existing role policy. This append is not atomic---it uses * {@link policy} to fetch the current policy and then {@link setPolicy} * to set the policy---and should not be used across concurrent sessions. * * @param policy The policy to append to the existing one. * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided */ appendPolicy(policy: RolePolicy, mfaReceipt?: MfaReceipts): Promise; /** * Get the policy for the role. * * @returns The policy for the role. */ policy(): Promise; /** * Set new edit policy (overwriting any edit policies previously set for this role) * * @param editPolicy The new edit policy to set * @param mfaReceipt Optional MFA receipt(s) * @throws if MFA is required and no receipts are provided */ setEditPolicy(editPolicy: EditPolicy, mfaReceipt?: MfaReceipts): Promise; /** * Get the edit policy for the role. * * @returns The edit policy for the role, undefined if there is no edit policy */ editPolicy(): Promise; /** * Sets the restricted actions on the role. * * @param restrictedActions The map of restricted actions * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided */ setRestrictedActions(restrictedActions: RestrictedActionsMap, mfaReceipt?: MfaReceipts): Promise; /** * @returns The list of all users with access to the role. * * @example [ * "User#c3b9379c-4e8c-4216-bd0a-65ace53cf98f", * "User#5593c25b-52e2-4fb5-b39b-96d41d681d82" * ] * * @param page Optional pagination options; by default, retrieves all users. */ users(page?: PageOpts): Promise; /** * Add an existing user to an existing role. * * @param userId The user-id of the user to add to the role. * @param mfaReceipt Optional MFA receipt(s) * @returns an empty response, or a response that can be used to approve MFA if needed. */ addUser(userId: string, mfaReceipt?: MfaReceipts): Promise>; /** * Remove an existing user from an existing role. * * @param userId The user-id of the user to remove from the role. * @param mfaReceipt Optional MFA receipt(s) * @returns an empty response, or a response that can be used to approve MFA if needed. */ removeUser(userId: string, mfaReceipt?: MfaReceipts): Promise>; /** * @returns The list of keys in the role. * * @example [ * { * id: "Key#bfe3eccb-731e-430d-b1e5-ac1363e6b06b", * policy: { TxReceiver: "0x8c594691c0e592ffa21f153a16ae41db5befcaaa" } * }, * ] * * @param page Optional pagination options; by default, retrieves all keys in this role. */ keys(page?: PageOpts): Promise; /** * Get a key in the role by its ID. * * @param keyId The ID of the key to get. * @param opts Optional options for getting the key. * @returns The key with its policies. */ getKey(keyId: string, opts?: GetRoleKeyOptions): Promise; /** * Add a list of existing keys to an existing role. * * @param keys The list of keys to add to the role. * @param policy The optional policy to apply to each key. * * @returns A CubeSigner response indicating success or failure. */ addKeys(keys: Key[], policy?: KeyPolicy): Promise>; /** * Add an existing key to an existing role. * * @param key The key to add to the role. * @param policy The optional policy to apply to the key. * * @returns A CubeSigner response indicating success or failure. */ addKey(key: Key, policy?: KeyPolicy): Promise>; /** * Remove an existing key from an existing role. * * @param key The key to remove from the role. * * @returns A CubeSigner response indicating success or failure. */ removeKey(key: Key): Promise>; /** * Create a new session for this role. * * @param purpose Descriptive purpose. * @param lifetimes Optional session lifetimes. * @param scopes Session scopes. Only `sign:*` scopes are allowed. * @returns New session. */ createSession(purpose: string, lifetimes?: SessionLifetime, scopes?: Scope[]): Promise; /** * List all signer sessions for this role. Returned objects can be used to * revoke individual sessions, but they cannot be used for authentication. * * @param page Optional pagination options; by default, retrieves all sessions. * @returns Signer sessions for this role. */ sessions(page?: PageOpts): Promise; /** * Constructor. * * @param apiClient The API client to use. * @param data The JSON response from the API server. * @internal */ constructor(apiClient: ApiClient, data: RoleInfo); /** * Update the role. * * @param request The JSON request to send to the API server. * @param mfaReceipt Optional MFA receipt(s) * @throws If MFA is required and no MFA receipts are provided * @returns The updated role information. */ private update; /** * Fetches the role information. * * @returns The role information. * @internal */ private fetch; } export {}; //# sourceMappingURL=role.d.ts.map