diff --git a/features/policies/examples/access-control.mdx b/features/policies/examples/access-control.mdx index db3c4d6f..27d103d8 100644 --- a/features/policies/examples/access-control.mdx +++ b/features/policies/examples/access-control.mdx @@ -99,6 +99,35 @@ and a request is made with the newer `V3` version, this policy with not allow th } ``` +#### Allow a specific user to perform a specific activity kind (full list [here](/features/policies/language#activity-kinds)) + +Unlike `activity.type`, which targets one exact version, `activity.kind` is version-agnostic: a +single `kind` matches every version of an activity. Prefer `activity.kind` when you want a policy to +keep working as activities are upgraded. For example, the policy below continues to allow the user to +create read write sessions even if Turnkey introduces a newer version such as +`ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V3`, because `CREATE_READ_WRITE_SESSION` matches all +versions. + +```json JSON +{ + "policyName": "Allow user to create read write sessions (any version)", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.id == '')", + "condition": "activity.kind == 'CREATE_READ_WRITE_SESSION'" +} +``` + +#### Allow a specific user to sign transactions across all versions + +```json JSON +{ + "policyName": "Allow user to sign transactions (any version)", + "effect": "EFFECT_ALLOW", + "consensus": "approvers.any(user, user.id == '')", + "condition": "activity.kind == 'SIGN_TRANSACTION'" +} +``` + #### Allow a specific credential type to perform a specific action (full list of credential types [here](/features/users/credentials#credential-types)) This policy can be used to say, only passkeys are allowed to sign transactions and not authentication through SMS (or any other authentication method). diff --git a/features/policies/language.mdx b/features/policies/language.mdx index 045c15bc..1655478f 100644 --- a/features/policies/language.mdx +++ b/features/policies/language.mdx @@ -86,6 +86,7 @@ The language is strongly typed which makes policies easy to author and maintain. | | credential_id | string | The credential ID of a passkey. Note: this is only populated for passkeys (also known as Authenticators within Turnkey resources), not API keys | | | public_key | string | The public key of the credential that approved the request | | **Activity** | type | string | The type of the activity (e.g. ACTIVITY_TYPE_SIGN_TRANSACTION_V2) | +| | kind | string | A version-agnostic grouping of the activity type. Unlike `type`, a single `kind` matches every version of an activity (e.g. `SIGN_TRANSACTION` matches both `ACTIVITY_TYPE_SIGN_TRANSACTION` and `ACTIVITY_TYPE_SIGN_TRANSACTION_V2`). Example values: `SIGN_TRANSACTION`, `CREATE_API_KEYS`, `CREATE_WALLET`, `CREATE_READ_WRITE_SESSION`. See [Activity kinds](#activity-kinds) for the full list of valid values and the kind → activity type mapping. | | | resource | string | The resource type the activity targets: `USER`, `PRIVATE_KEY`, `POLICY`, `WALLET`, `ORGANIZATION`, `INVITATION`, `CREDENTIAL`, `CONFIG`, `**RECOVERY`, `AUTH`, `OTP`, `PAYMENT_METHOD`, `SUBSCRIPTION` | | | action | string | The action of the activity: `CREATE`, `UPDATE`, `DELETE`, `SIGN`, `EXPORT`, `IMPORT` | | | params | struct | The parameters of the activity. See [here](#activity-parameters) for more details. | @@ -314,6 +315,113 @@ The language is strongly typed which makes policies easy to author and maintain. ** Legacy features, deprecated in the latest SDKs. +### Activity kinds + +`activity.kind` groups all versions of an activity under one version-agnostic value. The table +below lists each kind and the activity types it matches. + +| Kind | Matches Activity Types | +| ---- | ---------------------- | +| DELETE_ORGANIZATION | ACTIVITY_TYPE_DELETE_ORGANIZATION | +| CREATE_SUB_ORGANIZATION | ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V2, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V3, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V4, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V5, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V6, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V8 | +| DELETE_SUB_ORGANIZATION | ACTIVITY_TYPE_DELETE_SUB_ORGANIZATION | +| CREATE_INVITATIONS | ACTIVITY_TYPE_CREATE_INVITATIONS | +| DELETE_INVITATION | ACTIVITY_TYPE_DELETE_INVITATION | +| CREATE_USERS | ACTIVITY_TYPE_CREATE_USERS, ACTIVITY_TYPE_CREATE_USERS_V2, ACTIVITY_TYPE_CREATE_USERS_V3, ACTIVITY_TYPE_CREATE_USERS_V4 | +| CREATE_API_ONLY_USERS | ACTIVITY_TYPE_CREATE_API_ONLY_USERS | +| CREATE_USER_TAG | ACTIVITY_TYPE_CREATE_USER_TAG | +| UPDATE_USER | ACTIVITY_TYPE_UPDATE_USER | +| UPDATE_USER_NAME | ACTIVITY_TYPE_UPDATE_USER_NAME | +| UPDATE_USER_EMAIL | ACTIVITY_TYPE_UPDATE_USER_EMAIL | +| UPDATE_USER_PHONE_NUMBER | ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER | +| UPDATE_USER_TAG | ACTIVITY_TYPE_UPDATE_USER_TAG | +| DELETE_USERS | ACTIVITY_TYPE_DELETE_USERS | +| DELETE_USER_TAGS | ACTIVITY_TYPE_DELETE_USER_TAGS | +| ENABLE_AUTH_PROXY | ACTIVITY_TYPE_ENABLE_AUTH_PROXY | +| DISABLE_AUTH_PROXY | ACTIVITY_TYPE_DISABLE_AUTH_PROXY | +| CREATE_AUTHENTICATORS | ACTIVITY_TYPE_CREATE_AUTHENTICATORS, ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2 | +| CREATE_API_KEYS | ACTIVITY_TYPE_CREATE_API_KEYS, ACTIVITY_TYPE_CREATE_API_KEYS_V2 | +| DELETE_AUTHENTICATORS | ACTIVITY_TYPE_DELETE_AUTHENTICATORS | +| DELETE_API_KEYS | ACTIVITY_TYPE_DELETE_API_KEYS | +| CREATE_OAUTH_PROVIDERS | ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS, ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS_V2 | +| DELETE_OAUTH_PROVIDERS | ACTIVITY_TYPE_DELETE_OAUTH_PROVIDERS | +| CREATE_PRIVATE_KEYS | ACTIVITY_TYPE_CREATE_PRIVATE_KEYS, ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2 | +| CREATE_PRIVATE_KEY_TAG | ACTIVITY_TYPE_CREATE_PRIVATE_KEY_TAG | +| UPDATE_PRIVATE_KEY_TAG | ACTIVITY_TYPE_UPDATE_PRIVATE_KEY_TAG | +| DISABLE_PRIVATE_KEY | ACTIVITY_TYPE_DISABLE_PRIVATE_KEY | +| DELETE_PRIVATE_KEY_TAGS | ACTIVITY_TYPE_DELETE_PRIVATE_KEY_TAGS | +| INIT_IMPORT_PRIVATE_KEY | ACTIVITY_TYPE_INIT_IMPORT_PRIVATE_KEY | +| IMPORT_PRIVATE_KEY | ACTIVITY_TYPE_IMPORT_PRIVATE_KEY | +| DELETE_PRIVATE_KEYS | ACTIVITY_TYPE_DELETE_PRIVATE_KEYS | +| SIGN_TRANSACTION | ACTIVITY_TYPE_SIGN_TRANSACTION, ACTIVITY_TYPE_SIGN_TRANSACTION_V2 | +| SIGN_RAW_PAYLOAD | ACTIVITY_TYPE_SIGN_RAW_PAYLOAD, ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2 | +| SIGN_RAW_PAYLOADS | ACTIVITY_TYPE_SIGN_RAW_PAYLOADS | +| SPARK_SIGN_FROST | ACTIVITY_TYPE_SPARK_SIGN_FROST | +| SPARK_PREPARE_TRANSFER | ACTIVITY_TYPE_SPARK_PREPARE_TRANSFER | +| SPARK_CLAIM_TRANSFER | ACTIVITY_TYPE_SPARK_CLAIM_TRANSFER | +| SPARK_PREPARE_LIGHTNING_RECEIVE | ACTIVITY_TYPE_SPARK_PREPARE_LIGHTNING_RECEIVE | +| ETH_SEND_TRANSACTION | ACTIVITY_TYPE_ETH_SEND_TRANSACTION, ACTIVITY_TYPE_ETH_SEND_TRANSACTION_V2 | +| SOL_SEND_TRANSACTION | ACTIVITY_TYPE_SOL_SEND_TRANSACTION | +| EXPORT_PRIVATE_KEY | ACTIVITY_TYPE_EXPORT_PRIVATE_KEY | +| CREATE_WALLET | ACTIVITY_TYPE_CREATE_WALLET | +| CREATE_WALLET_ACCOUNTS | ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS | +| EXPORT_WALLET | ACTIVITY_TYPE_EXPORT_WALLET | +| EXPORT_WALLET_ACCOUNT | ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT | +| INIT_IMPORT_WALLET | ACTIVITY_TYPE_INIT_IMPORT_WALLET | +| IMPORT_WALLET | ACTIVITY_TYPE_IMPORT_WALLET | +| DELETE_WALLETS | ACTIVITY_TYPE_DELETE_WALLETS | +| UPDATE_WALLET | ACTIVITY_TYPE_UPDATE_WALLET | +| DELETE_WALLET_ACCOUNTS | ACTIVITY_TYPE_DELETE_WALLET_ACCOUNTS | +| INIT_FIAT_ON_RAMP | ACTIVITY_TYPE_INIT_FIAT_ON_RAMP | +| CREATE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_CREATE_FIAT_ON_RAMP_CREDENTIAL | +| DELETE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_DELETE_FIAT_ON_RAMP_CREDENTIAL | +| UPDATE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_UPDATE_FIAT_ON_RAMP_CREDENTIAL | +| CREATE_POLICY | ACTIVITY_TYPE_CREATE_POLICY, ACTIVITY_TYPE_CREATE_POLICY_V2, ACTIVITY_TYPE_CREATE_POLICY_V3 | +| CREATE_POLICIES | ACTIVITY_TYPE_CREATE_POLICIES | +| UPDATE_POLICY | ACTIVITY_TYPE_UPDATE_POLICY, ACTIVITY_TYPE_UPDATE_POLICY_V2 | +| DELETE_POLICY | ACTIVITY_TYPE_DELETE_POLICY | +| DELETE_POLICIES | ACTIVITY_TYPE_DELETE_POLICIES | +| ACTIVATE_BILLING_TIER | ACTIVITY_TYPE_ACTIVATE_BILLING_TIER | +| SET_PAYMENT_METHOD | ACTIVITY_TYPE_SET_PAYMENT_METHOD, ACTIVITY_TYPE_SET_PAYMENT_METHOD_V2 | +| DELETE_PAYMENT_METHOD | ACTIVITY_TYPE_DELETE_PAYMENT_METHOD | +| UPDATE_ALLOWED_ORIGINS | ACTIVITY_TYPE_UPDATE_ALLOWED_ORIGINS | +| CREATE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_CREATE_WEBHOOK_ENDPOINT | +| UPDATE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_UPDATE_WEBHOOK_ENDPOINT | +| DELETE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_DELETE_WEBHOOK_ENDPOINT | +| INIT_USER_EMAIL_RECOVERY | ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY, ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2 | +| EMAIL_AUTH | ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2, ACTIVITY_TYPE_EMAIL_AUTH_V3 | +| INIT_OTP_AUTH | ACTIVITY_TYPE_INIT_OTP_AUTH, ACTIVITY_TYPE_INIT_OTP_AUTH_V2, ACTIVITY_TYPE_INIT_OTP_AUTH_V3 | +| OTP_AUTH | ACTIVITY_TYPE_OTP_AUTH | +| OAUTH | ACTIVITY_TYPE_OAUTH | +| CREATE_READ_WRITE_SESSION | ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION, ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2 | +| OAUTH_LOGIN | ACTIVITY_TYPE_OAUTH_LOGIN | +| OTP_LOGIN | ACTIVITY_TYPE_OTP_LOGIN, ACTIVITY_TYPE_OTP_LOGIN_V2 | +| STAMP_LOGIN | ACTIVITY_TYPE_STAMP_LOGIN | +| UPDATE_AUTH_PROXY_CONFIG | ACTIVITY_TYPE_UPDATE_AUTH_PROXY_CONFIG | +| CREATE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_CREATE_OAUTH2_CREDENTIAL | +| UPDATE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_UPDATE_OAUTH2_CREDENTIAL | +| DELETE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_DELETE_OAUTH2_CREDENTIAL | +| OAUTH2_AUTHENTICATE | ACTIVITY_TYPE_OAUTH2_AUTHENTICATE | +| INIT_OTP | ACTIVITY_TYPE_INIT_OTP, ACTIVITY_TYPE_INIT_OTP_V2, ACTIVITY_TYPE_INIT_OTP_V3 | +| VERIFY_OTP | ACTIVITY_TYPE_VERIFY_OTP, ACTIVITY_TYPE_VERIFY_OTP_V2 | +| CREATE_SMART_CONTRACT_INTERFACE | ACTIVITY_TYPE_CREATE_SMART_CONTRACT_INTERFACE | +| DELETE_SMART_CONTRACT_INTERFACE | ACTIVITY_TYPE_DELETE_SMART_CONTRACT_INTERFACE | +| UPSERT_GAS_USAGE_CONFIG | ACTIVITY_TYPE_UPSERT_GAS_USAGE_CONFIG | +| CREATE_TVC_APP | ACTIVITY_TYPE_CREATE_TVC_APP | +| CREATE_TVC_DEPLOYMENT | ACTIVITY_TYPE_CREATE_TVC_DEPLOYMENT | +| CREATE_TVC_MANIFEST_APPROVALS | ACTIVITY_TYPE_CREATE_TVC_MANIFEST_APPROVALS | +| UPDATE_TVC_APP_LIVE_DEPLOYMENT | ACTIVITY_TYPE_UPDATE_TVC_APP_LIVE_DEPLOYMENT | +| DELETE_TVC_DEPLOYMENT | ACTIVITY_TYPE_DELETE_TVC_DEPLOYMENT | +| DELETE_TVC_APP_AND_DEPLOYMENTS | ACTIVITY_TYPE_DELETE_TVC_APP_AND_DEPLOYMENTS | +| RESTORE_TVC_DEPLOYMENT | ACTIVITY_TYPE_RESTORE_TVC_DEPLOYMENT | +| POST_TVC_QUORUM_KEY_SHARE | ACTIVITY_TYPE_POST_TVC_QUORUM_KEY_SHARE | + + + Prefer `activity.kind` over `activity.type` when you want a policy to apply across all versions + of an activity. `activity.type` targets one exact version and will not match newer versions + introduced later. + + ## Appendix ### Policy evaluation