stytch 10.25.0 → 10.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2f709cf39fcc571c655a577f0846ef68c7767d4aeace2f2ea71f3d85781018
-  data.tar.gz: afc3c7c5ce1dd327d2c5ab25f1b130eb25c355207bd8a15ac9db2c986b3f7eda
+  metadata.gz: 0a905e33f9cc2881ad04adabc476f64db1cfc8836b1e012dd6692bd411ff32cd
+  data.tar.gz: bfa6c0c4d4858a8f7154bb85b359bd311b0ea17becf11fb89373bb721fe74d0f
 SHA512:
-  metadata.gz: 9e1391f4ed96c281b6303f26532211f75332ce36fa012eba7629d2d2c6982b8fae6366778cff1b54a6b847e7893dac7926080e387893acb6d4efdd0a1029fb5c
-  data.tar.gz: 94b8e29c50c8901bdb605e729de1440deaf73682d53e1da186862267a77bf7fc6545f63aec865fc25b61273da56d2c348b40d811e7b5690315158593bad5c49c
+  metadata.gz: acb3ded234b14fd6fbff16c1e15942a6a7b30bf30e4d3c763b0645e2e61c9bb7aab86f3b8583b1e5aa338bba49b36fd70f80887aed449dfcf854defac6bf0ede
+  data.tar.gz: 00cc8b6ad8d878561322055da00b0fed3a2265dbb7171ab46f89594fe0ba43636b8f86cd0c04c0f0b57c3ec89f0114f82667ef46d021697066bf0fb0a66d726b

data/lib/stytch/b2b_client.rb

@@ -1,6 +1,13 @@
+# !!!
+# WARNING: This file is autogenerated
+# Only modify code within MANUAL() sections
+# or your changes may be overwritten later!
+# !!!
+
 # frozen_string_literal: true
 
 require_relative 'b2b_discovery'
+require_relative 'b2b_idp'
 require_relative 'b2b_impersonation'
 require_relative 'b2b_magic_links'
 require_relative 'b2b_oauth'
@@ -23,7 +30,7 @@ module StytchB2B
   class Client
     ENVIRONMENTS = %i[live test].freeze
 
-    attr_reader :connected_app, :discovery, :fraud, :impersonation, :m2m, :magic_links, :oauth, :otps, :organizations, :passwords, :project, :rbac, :recovery_codes, :scim, :sso, :sessions, :totps
+    attr_reader :connected_app, :discovery, :fraud, :impersonation, :m2m, :magic_links, :oauth, :otps, :organizations, :passwords, :project, :rbac, :recovery_codes, :scim, :sso, :sessions, :totps, :idp
 
     def initialize(project_id:, secret:, env: nil, fraud_env: nil, &block)
       @api_host = api_host(env, project_id)
@@ -35,7 +42,8 @@ module StytchB2B
       create_connection(&block)
 
       rbac = StytchB2B::RBAC.new(@connection)
-      @policy_cache = StytchB2B::PolicyCache.new(rbac_client: rbac)
+      @policy_cache = Stytch::PolicyCache.new(rbac_client: rbac)
+      @idp = StytchB2B::IDP.new(@connection, @project_id, @policy_cache)
 
       @connected_app = Stytch::ConnectedApp.new(@connection)
       @discovery = StytchB2B::Discovery.new(@connection)

data/lib/stytch/b2b_discovery.rb

@@ -197,7 +197,7 @@ module StytchB2B
       # sso_jit_provisioning::
       #   The authentication setting that controls the JIT provisioning of Members when authenticating via SSO. The accepted values are:
       #
-      #   `ALL_ALLOWED` – new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
+      #   `ALL_ALLOWED` – the default setting, new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
       #
       #   `RESTRICTED` – only new Members with SSO logins that comply with `sso_jit_provisioning_allowed_connections` can be provisioned upon authentication.
       #
@@ -215,7 +215,7 @@ module StytchB2B
       #
       #   `RESTRICTED` – only new Members with verified emails that comply with `email_allowed_domains` can be provisioned upon authentication via Email Magic Link or OAuth.
       #
-      #   `NOT_ALLOWED` – disable JIT provisioning via Email Magic Link and OAuth.
+      #   `NOT_ALLOWED` – the default setting, disables JIT provisioning via Email Magic Link and OAuth.
       #
       #   The type of this field is nilable +String+.
       # email_invites::
@@ -273,7 +273,7 @@ module StytchB2B
       #
       #   `RESTRICTED` – only new Members with tenants in `allowed_oauth_tenants` can JIT provision via tenant.
       #
-      #   `NOT_ALLOWED` – disable JIT provisioning by OAuth Tenant.
+      #   `NOT_ALLOWED` – the default setting, disables JIT provisioning by OAuth Tenant.
       #
       #   The type of this field is nilable +String+.
       # allowed_oauth_tenants::
@@ -282,7 +282,7 @@ module StytchB2B
       # first_party_connected_apps_allowed_type::
       #   The authentication setting that sets the Organization's policy towards first party Connected Apps. The accepted values are:
       #
-      #   `ALL_ALLOWED` – any first party Connected App in the Project is permitted for use by Members.
+      #   `ALL_ALLOWED` – the default setting, any first party Connected App in the Project is permitted for use by Members.
       #
       #   `RESTRICTED` – only first party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
       #
@@ -295,7 +295,7 @@ module StytchB2B
       # third_party_connected_apps_allowed_type::
       #   The authentication setting that sets the Organization's policy towards third party Connected Apps. The accepted values are:
       #
-      #   `ALL_ALLOWED` – any third party Connected App in the Project is permitted for use by Members.
+      #   `ALL_ALLOWED` – the default setting, any third party Connected App in the Project is permitted for use by Members.
       #
       #   `RESTRICTED` – only third party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
       #

data/lib/stytch/b2b_idp.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'json/jwt'
+require_relative 'errors'
+require_relative 'request_helper'
+require_relative 'rbac_local'
+
+module StytchB2B
+  class IDP
+    include Stytch::RequestHelper
+
+    def initialize(connection, project_id, policy_cache)
+      @connection = connection
+      @project_id = project_id
+      @policy_cache = policy_cache
+      @non_custom_claim_keys = [
+        'aud',
+        'exp',
+        'iat',
+        'iss',
+        'jti',
+        'nbf',
+        'sub',
+        'active',
+        'client_id',
+        'request_id',
+        'scope',
+        'status_code',
+        'token_type',
+        'https://stytch.com/organization'
+      ]
+    end
+
+    # Introspects a token JWT from an authorization code response.
+    # Access tokens are JWTs signed with the project's JWKs. Refresh tokens are opaque tokens.
+    # Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+    #
+    # == Parameters:
+    # token::
+    #   The access token (or refresh token) to introspect.
+    #   The type of this field is +String+.
+    # client_id::
+    #   The ID of the client.
+    #   The type of this field is +String+.
+    # client_secret::
+    #   The secret of the client.
+    #   The type of this field is nilable +String+.
+    # token_type_hint::
+    #   A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+    #   The type of this field is +String+.
+    # authorization_check::
+    #   Optional authorization check object.
+    #   The type of this field is nilable +Hash+.
+    #
+    # == Returns:
+    # An object with the following fields:
+    # subject::
+    #   The subject of the token.
+    #   The type of this field is +String+.
+    # scope::
+    #   The scope of the token.
+    #   The type of this field is +String+.
+    # audience::
+    #   The audience of the token.
+    #   The type of this field is +String+.
+    # expires_at::
+    #   The expiration time of the token.
+    #   The type of this field is +Integer+.
+    # issued_at::
+    #   The issued at time of the token.
+    #   The type of this field is +Integer+.
+    # issuer::
+    #   The issuer of the token.
+    #   The type of this field is +String+.
+    # not_before::
+    #   The not before time of the token.
+    #   The type of this field is +Integer+.
+    # token_type::
+    #   The type of the token.
+    #   The type of this field is +String+.
+    # custom_claims::
+    #   Custom claims in the token.
+    #   The type of this field is +Hash+.
+    # organization_claim::
+    #   The organization claim in the token.
+    #   The type of this field is +Hash+.
+    def introspect_token_network(
+      token:,
+      client_id:,
+      client_secret: nil,
+      token_type_hint: 'access_token',
+      authorization_check: nil
+    )
+      headers = {}
+      data = {
+        'token' => token,
+        'client_id' => client_id,
+        'token_type_hint' => token_type_hint
+      }
+      data['client_secret'] = client_secret unless client_secret.nil?
+
+      url = @connection.url_prefix + '/v1/oauth2/introspect'
+      jwt_response = post_request(url, data, headers)
+
+      return nil unless jwt_response['active']
+
+      custom_claims = jwt_response.reject { |k, _| @non_custom_claim_keys.include?(k) }
+      organization_claim = jwt_response['https://stytch.com/organization']
+      organization_id = organization_claim['organization_id']
+      scope = jwt_response['scope']
+
+      if authorization_check
+        @policy_cache.perform_authorization_check(
+          subject_roles: scope.split,
+          authorization_check: authorization_check,
+          subject_org_id: organization_id
+        )
+      end
+
+      {
+        'subject' => jwt_response['sub'],
+        'scope' => jwt_response['scope'],
+        'audience' => jwt_response['aud'],
+        'expires_at' => jwt_response['exp'],
+        'issued_at' => jwt_response['iat'],
+        'issuer' => jwt_response['iss'],
+        'not_before' => jwt_response['nbf'],
+        'token_type' => jwt_response['token_type'],
+        'custom_claims' => custom_claims,
+        'organization_claim' => organization_claim
+      }
+    end
+
+    # Introspects a token JWT from an authorization code response.
+    # Access tokens are JWTs signed with the project's JWKs. Refresh tokens are opaque tokens.
+    # Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+    #
+    # == Parameters:
+    # access_token::
+    #   The access token (or refresh token) to introspect.
+    #   The type of this field is +String+.
+    # authorization_check::
+    #   Optional authorization check object.
+    #   The type of this field is nilable +Hash+.
+    #
+    # == Returns:
+    # An object with the following fields:
+    # subject::
+    #   The subject of the token.
+    #   The type of this field is +String+.
+    # scope::
+    #   The scope of the token.
+    #   The type of this field is +String+.
+    # audience::
+    #   The audience of the token.
+    #   The type of this field is +String+.
+    # expires_at::
+    #   The expiration time of the token.
+    #   The type of this field is +Integer+.
+    # issued_at::
+    #   The issued at time of the token.
+    #   The type of this field is +Integer+.
+    # issuer::
+    #   The issuer of the token.
+    #   The type of this field is +String+.
+    # not_before::
+    #   The not before time of the token.
+    #   The type of this field is +Integer+.
+    # token_type::
+    #   The type of the token.
+    #   The type of this field is +String+.
+    # custom_claims::
+    #   Custom claims in the token.
+    #   The type of this field is +Hash+.
+    # organization_claim::
+    #   The organization claim in the token.
+    #   The type of this field is +Hash+.
+    def introspect_access_token_local(
+      access_token:,
+      authorization_check: nil
+    )
+      scope_claim = 'scope'
+      organization_claim = 'https://stytch.com/organization'
+
+      # Create a JWKS loader similar to other classes in the codebase
+      @cache_last_update = 0
+      jwks_loader = lambda do |options|
+        @cached_keys = nil if options[:invalidate] && @cache_last_update < Time.now.to_i - 300
+        if @cached_keys.nil?
+          @cached_keys = get_jwks(project_id: @project_id)
+          @cache_last_update = Time.now.to_i
+        end
+        @cached_keys
+      end
+
+      begin
+        decoded_jwt = JWT.decode(
+          access_token,
+          nil,
+          true,
+          {
+            algorithms: ['RS256'],
+            jwks: jwks_loader,
+            iss: ["stytch.com/#{@project_id}", @connection.url_prefix],
+            aud: @project_id
+          }
+        )[0]
+
+        generic_claims = decoded_jwt
+        custom_claims = generic_claims.reject { |k, _| @non_custom_claim_keys.include?(k) }
+        organization_claim_data = generic_claims[organization_claim]
+        organization_id = organization_claim_data['organization_id']
+        scope = generic_claims[scope_claim]
+
+        if authorization_check
+          @policy_cache.perform_authorization_check(
+            subject_roles: scope.split,
+            authorization_check: authorization_check,
+            subject_org_id: organization_id
+          )
+        end
+
+        {
+          'subject' => generic_claims['sub'],
+          'scope' => generic_claims[scope_claim],
+          'audience' => generic_claims['aud'],
+          'expires_at' => generic_claims['exp'],
+          'issued_at' => generic_claims['iat'],
+          'issuer' => generic_claims['iss'],
+          'not_before' => generic_claims['nbf'],
+          'token_type' => 'access_token',
+          'custom_claims' => custom_claims,
+          'organization_claim' => organization_claim_data
+        }
+      rescue JWT::InvalidIssuerError
+        raise Stytch::JWTInvalidIssuerError
+      rescue JWT::InvalidAudError
+        raise Stytch::JWTInvalidAudienceError
+      rescue JWT::ExpiredSignature
+        raise Stytch::JWTExpiredSignatureError
+      rescue JWT::IncorrectAlgorithm
+        raise Stytch::JWTIncorrectAlgorithmError
+      rescue JWT::DecodeError
+        nil
+      end
+    end
+
+    # Gets the JWKS for the project.
+    #
+    # == Parameters:
+    # project_id::
+    #   The ID of the project.
+    #   The type of this field is +String+.
+    #
+    # == Returns:
+    # The JWKS for the project.
+    #   The type of this field is +Hash+.
+    def get_jwks(project_id:)
+      headers = {}
+      query_params = {}
+      request = request_with_query_params("/v1/b2b/sessions/jwks/#{project_id}", query_params)
+      get_request(request, headers)
+    end
+  end
+end

data/lib/stytch/b2b_organizations.rb

@@ -97,7 +97,7 @@ module StytchB2B
 
     # Creates an Organization. An `organization_name` and a unique `organization_slug` are required.
     #
-    # By default, `email_invites` and `sso_jit_provisioning` will be set to `ALL_ALLOWED`, and `mfa_policy` will be set to `OPTIONAL` if no Organization authentication settings are explicitly defined in the request.
+    # If no Organization authentication setting parameters are passed in, `email_invites` will default to `ALL_ALLOWED` so that the Organization has a way to add Members. Otherwise, `email_invites` will default to `NOT_ALLOWED`.
     #
     # *See the [Organization authentication settings](https://stytch.com/docs/b2b/api/org-auth-settings) resource to learn more about fields like `email_jit_provisioning`, `email_invites`, `sso_jit_provisioning`, etc., and their behaviors.
     #
@@ -117,7 +117,7 @@ module StytchB2B
     # sso_jit_provisioning::
     #   The authentication setting that controls the JIT provisioning of Members when authenticating via SSO. The accepted values are:
     #
-    #   `ALL_ALLOWED` – new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
+    #   `ALL_ALLOWED` – the default setting, new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
     #
     #   `RESTRICTED` – only new Members with SSO logins that comply with `sso_jit_provisioning_allowed_connections` can be provisioned upon authentication.
     #
@@ -135,7 +135,7 @@ module StytchB2B
     #
     #   `RESTRICTED` – only new Members with verified emails that comply with `email_allowed_domains` can be provisioned upon authentication via Email Magic Link or OAuth.
     #
-    #   `NOT_ALLOWED` – disable JIT provisioning via Email Magic Link and OAuth.
+    #   `NOT_ALLOWED` – the default setting, disables JIT provisioning via Email Magic Link and OAuth.
     #
     #   The type of this field is nilable +String+.
     # email_invites::
@@ -193,7 +193,7 @@ module StytchB2B
     #
     #   `RESTRICTED` – only new Members with tenants in `allowed_oauth_tenants` can JIT provision via tenant.
     #
-    #   `NOT_ALLOWED` – disable JIT provisioning by OAuth Tenant.
+    #   `NOT_ALLOWED` – the default setting, disables JIT provisioning by OAuth Tenant.
     #
     #   The type of this field is nilable +String+.
     # allowed_oauth_tenants::
@@ -205,7 +205,7 @@ module StytchB2B
     # first_party_connected_apps_allowed_type::
     #   The authentication setting that sets the Organization's policy towards first party Connected Apps. The accepted values are:
     #
-    #   `ALL_ALLOWED` – any first party Connected App in the Project is permitted for use by Members.
+    #   `ALL_ALLOWED` – the default setting, any first party Connected App in the Project is permitted for use by Members.
     #
     #   `RESTRICTED` – only first party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
     #
@@ -218,7 +218,7 @@ module StytchB2B
     # third_party_connected_apps_allowed_type::
     #   The authentication setting that sets the Organization's policy towards third party Connected Apps. The accepted values are:
     #
-    #   `ALL_ALLOWED` – any third party Connected App in the Project is permitted for use by Members.
+    #   `ALL_ALLOWED` – the default setting, any third party Connected App in the Project is permitted for use by Members.
     #
     #   `RESTRICTED` – only third party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
     #
@@ -354,7 +354,7 @@ module StytchB2B
     # sso_jit_provisioning::
     #   The authentication setting that controls the JIT provisioning of Members when authenticating via SSO. The accepted values are:
     #
-    #   `ALL_ALLOWED` – new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
+    #   `ALL_ALLOWED` – the default setting, new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
     #
     #   `RESTRICTED` – only new Members with SSO logins that comply with `sso_jit_provisioning_allowed_connections` can be provisioned upon authentication.
     #
@@ -382,7 +382,7 @@ module StytchB2B
     #
     #   `RESTRICTED` – only new Members with verified emails that comply with `email_allowed_domains` can be provisioned upon authentication via Email Magic Link or OAuth.
     #
-    #   `NOT_ALLOWED` – disable JIT provisioning via Email Magic Link and OAuth.
+    #   `NOT_ALLOWED` – the default setting, disables JIT provisioning via Email Magic Link and OAuth.
     #
     #
     # If this field is provided and a session header is passed into the request, the Member Session must have permission to perform the `update.settings.email-jit-provisioning` action on the `stytch.organization` Resource.
@@ -456,7 +456,7 @@ module StytchB2B
     #
     #   `RESTRICTED` – only new Members with tenants in `allowed_oauth_tenants` can JIT provision via tenant.
     #
-    #   `NOT_ALLOWED` – disable JIT provisioning by OAuth Tenant.
+    #   `NOT_ALLOWED` – the default setting, disables JIT provisioning by OAuth Tenant.
     #
     #
     # If this field is provided and a session header is passed into the request, the Member Session must have permission to perform the `update.settings.oauth-tenant-jit-provisioning` action on the `stytch.organization` Resource.
@@ -472,7 +472,7 @@ module StytchB2B
     # first_party_connected_apps_allowed_type::
     #   The authentication setting that sets the Organization's policy towards first party Connected Apps. The accepted values are:
     #
-    #   `ALL_ALLOWED` – any first party Connected App in the Project is permitted for use by Members.
+    #   `ALL_ALLOWED` – the default setting, any first party Connected App in the Project is permitted for use by Members.
     #
     #   `RESTRICTED` – only first party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
     #
@@ -485,7 +485,7 @@ module StytchB2B
     # third_party_connected_apps_allowed_type::
     #   The authentication setting that sets the Organization's policy towards third party Connected Apps. The accepted values are:
     #
-    #   `ALL_ALLOWED` – any third party Connected App in the Project is permitted for use by Members.
+    #   `ALL_ALLOWED` – the default setting, any third party Connected App in the Project is permitted for use by Members.
     #
     #   `RESTRICTED` – only third party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
     #
@@ -1507,6 +1507,8 @@ module StytchB2B
       # The member will receive an Email Magic Link that expires in 5 minutes. If they do not verify their new email address in that timeframe, the email
       # will be freed up for other members to use.
       #
+      # The Magic Link will redirect to your `login_redirect_url` (or the configured default if one isn't provided), and you should invoke the [Authenticate Magic Link](https://stytch.com/docs/b2b/api/authenticate-magic-link) endpoint as normal to complete the flow.
+      #
       # == Parameters:
       # organization_id::
       #   Globally unique UUID that identifies a specific Organization. The `organization_id` is critical to perform operations on an Organization, so be sure to preserve this value. You may also use the organization_slug here as a convenience.
@@ -1515,7 +1517,7 @@ module StytchB2B
       #   Globally unique UUID that identifies a specific Member. The `member_id` is critical to perform operations on a Member, so be sure to preserve this value. You may use an external_id here if one is set for the member.
       #   The type of this field is +String+.
       # email_address::
-      #   The email address of the Member.
+      #   The new email address for the Member.
       #   The type of this field is +String+.
       # login_redirect_url::
       #   The URL that the Member clicks from the login Email Magic Link. This URL should be an endpoint in the backend server that

data/lib/stytch/b2b_otp.rb

@@ -38,14 +38,16 @@ module StytchB2B
       #
       # If a Member has a phone number and is enrolled in MFA, then after a successful primary authentication event (e.g. [email magic link](https://stytch.com/docs/b2b/api/authenticate-magic-link) or [SSO](https://stytch.com/docs/b2b/api/sso-authenticate) login is complete), an SMS OTP will automatically be sent to their phone number. In that case, this endpoint should only be used for subsequent authentication events, such as prompting a Member for an OTP again after a period of inactivity.
       #
-      # Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the Member ID passed.
+      # If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+      #
+      # Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must match the `member_id` passed.
       #
       # ### Cost to send SMS OTP
       # Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
       #
       # Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
       #
-      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
       #
       # == Parameters:
       # organization_id::

data/lib/stytch/b2b_passwords.rb

@@ -623,6 +623,9 @@ module StytchB2B
       #
       # == Returns:
       # An object with the following fields:
+      # request_id::
+      #   Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+      #   The type of this field is +String+.
       # status_code::
       #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
       #   The type of this field is +Integer+.

data/lib/stytch/b2b_rbac.rb

@@ -20,7 +20,7 @@ module StytchB2B
     #
     # When using the backend SDKs, the RBAC Policy will be cached to allow for local evaluations, eliminating the need for an extra request to Stytch. The policy will be refreshed if an authorization check is requested and the RBAC policy was last updated more than 5 minutes ago.
     #
-    # Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/docs/dashboard/rbac) in the Dashboard.
+    # Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/dashboard/rbac) in the Dashboard.
     # Additionally, [Role assignment](https://stytch.com/docs/b2b/guides/rbac/role-assignment) can be programmatically managed through certain Stytch API endpoints.
     #
     # Check out the [RBAC overview](https://stytch.com/docs/b2b/guides/rbac/overview) to learn more about Stytch's RBAC permissioning model.
@@ -36,7 +36,7 @@ module StytchB2B
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
     # policy::
-    #   The RBAC Policy document that contains all defined Roles and Resources – which are managed in the [Dashboard](https://stytch.com/docs/dashboard/rbac). Read more about these entities and how they work in our [RBAC overview](https://stytch.com/docs/b2b/guides/rbac/overview).
+    #   The RBAC Policy document that contains all defined Roles and Resources – which are managed in the [Dashboard](https://stytch.com/dashboard/rbac). Read more about these entities and how they work in our [RBAC overview](https://stytch.com/docs/b2b/guides/rbac/overview).
     #   The type of this field is nilable +Policy+ (+object+).
     def policy
       headers = {}

data/lib/stytch/b2b_sessions.rb

@@ -164,7 +164,7 @@ module StytchB2B
     #   The type of this field is +Integer+.
     # verdict::
     #   If an `authorization_check` is provided in the request and the check succeeds, this field will return
-    #   the complete list of Roles that gave the Member permission to perform the specified action on the specified Resource.
+    #   information about why the Member was granted permission.
     #   The type of this field is nilable +AuthorizationVerdict+ (+object+).
     def authenticate(
       session_token: nil,
@@ -417,7 +417,7 @@ module StytchB2B
       post_request('/v1/b2b/sessions/exchange_access_token', request, headers)
     end
 
-    # Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens).  If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
+    # Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/dashboard/trusted-auth-tokens).  If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
     #
     # == Parameters:
     # organization_id::
@@ -504,7 +504,7 @@ module StytchB2B
     end
 
     # Migrate a session from an external OIDC compliant endpoint.
-    # Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the [Dashboard](https://stytch.com/docs/dashboard), and then perform a lookup using the `session_token`. <!-- FIXME more specific dashboard link-->
+    # Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the [Dashboard](https://stytch.com/dashboard/migrations), and then perform a lookup using the `session_token`.
     # If the response contains a valid email address, Stytch will attempt to match that email address with an existing Member in your Organization and create a Stytch Session.
     # You will need to create the member before using this endpoint.
     #

data/lib/stytch/b2b_totps.rb

@@ -18,7 +18,9 @@ module StytchB2B
 
     # Create a new TOTP instance for a Member. The Member can use the authenticator application of their choice to scan the QR code or enter the secret.
     #
-    # Passing an intermediate session token, session token, or session JWT is not required, but if passed must match the Member ID passed.
+    # If the Member already has an active MFA factor, then passing an intermediate session token, session token, or session JWT with the existing MFA factor on it is required to prevent bypassing MFA.
+    #
+    # Otherwise, passing an intermediate session token, session token, or session JWT is not required, but if passed must match the `member_id` passed.
     #
     # == Parameters:
     # organization_id::

data/lib/stytch/client.rb

@@ -1,8 +1,15 @@
+# !!!
+# WARNING: This file is autogenerated
+# Only modify code within MANUAL() sections
+# or your changes may be overwritten later!
+# !!!
+
 # frozen_string_literal: true
 
 require_relative 'connected_apps'
 require_relative 'crypto_wallets'
 require_relative 'fraud'
+require_relative 'idp'
 require_relative 'impersonation'
 require_relative 'm2m'
 require_relative 'magic_links'
@@ -10,6 +17,8 @@ require_relative 'oauth'
 require_relative 'otps'
 require_relative 'passwords'
 require_relative 'project'
+require_relative 'rbac'
+require_relative 'rbac_local'
 require_relative 'sessions'
 require_relative 'totps'
 require_relative 'users'
@@ -19,7 +28,7 @@ module Stytch
   class Client
     ENVIRONMENTS = %i[live test].freeze
 
-    attr_reader :connected_app, :crypto_wallets, :fraud, :impersonation, :m2m, :magic_links, :oauth, :otps, :passwords, :project, :sessions, :totps, :users, :webauthn
+    attr_reader :connected_app, :crypto_wallets, :fraud, :impersonation, :m2m, :magic_links, :oauth, :otps, :passwords, :project, :rbac, :sessions, :totps, :users, :webauthn, :idp
 
     def initialize(project_id:, secret:, env: nil, fraud_env: nil, &block)
       @api_host = api_host(env, project_id)
@@ -30,6 +39,10 @@ module Stytch
 
       create_connection(&block)
 
+      rbac = Stytch::RBAC.new(@connection)
+      @policy_cache = Stytch::PolicyCache.new(rbac_client: rbac)
+      @idp = Stytch::IDP.new(@connection, @project_id, @policy_cache)
+
       @connected_app = Stytch::ConnectedApp.new(@connection)
       @crypto_wallets = Stytch::CryptoWallets.new(@connection)
       @fraud = Stytch::Fraud.new(@fraud_connection)
@@ -40,7 +53,8 @@ module Stytch
       @otps = Stytch::OTPs.new(@connection)
       @passwords = Stytch::Passwords.new(@connection)
       @project = Stytch::Project.new(@connection)
-      @sessions = Stytch::Sessions.new(@connection, @project_id)
+      @rbac = Stytch::RBAC.new(@connection)
+      @sessions = Stytch::Sessions.new(@connection, @project_id, @policy_cache)
       @totps = Stytch::TOTPs.new(@connection)
       @users = Stytch::Users.new(@connection)
       @webauthn = Stytch::WebAuthn.new(@connection)

data/lib/stytch/fraud.rb

@@ -28,14 +28,17 @@ module Stytch
         @connection = connection
       end
 
-      # Lookup the associated fingerprint for the `telemetry_id` returned from the `GetTelemetryID()` function. Learn more about the different fingerprint types and verdicts in our [DFP guide](https://stytch.com/docs/fraud/guides/device-fingerprinting/overview).
+      # Lookup the associated fingerprint for the `telemetry_id` returned from the `GetTelemetryID()` function.
+      # Learn more about the different fingerprint types and verdicts in our [DFP guide](https://stytch.com/docs/fraud/guides/device-fingerprinting/overview).
       #
-      # Make a decision based on the returned `verdict`:
+      # You can make a decision based on the recommended `verdict` in the response:
       # * `ALLOW` - This is a known valid device grouping or device profile that is part of the default `ALLOW` listed set of known devices by Stytch. This grouping is made up of  verified device profiles that match the characteristics of known/authentic traffic origins.
       # * `BLOCK` - This is a known bad or malicious device profile that is undesirable and should be blocked from completing the privileged action in question.
       # * `CHALLENGE` - This is an unknown or potentially malicious device that should be put through increased friction such as 2FA or other forms of extended user verification before allowing the privileged action to proceed.
       #
-      # If the `telemetry_id` is not found, we will return a 404 `telemetry_id_not_found` [error](https://stytch.com/docs/fraud/api/errors/404#telemetry_id_not_found). We recommend treating 404 errors as a `BLOCK`, since it could be a sign of an attacker trying to bypass DFP protections by generating fake telemetry IDs.
+      # If the `telemetry_id` is expired or not found, this endpoint returns a 404 `telemetry_id_not_found` [error](https://stytch.com/docs/fraud/api/errors/404#telemetry_id_not_found).
+      # We recommend treating 404 errors as a `BLOCK`, since it could be a sign of an attacker trying to bypass DFP protections.
+      # See [Attacker-controlled telemetry IDs](https://stytch.com/docs/fraud/guides/device-fingerprinting/integration-steps/test-your-integration#attacker-controlled-telemetry-ids) for more information.
       #
       # == Parameters:
       # telemetry_id::

data/lib/stytch/idp.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'json/jwt'
+require_relative 'errors'
+require_relative 'request_helper'
+require_relative 'rbac_local'
+
+module Stytch
+  class IDP
+    include Stytch::RequestHelper
+
+    def initialize(connection, project_id, policy_cache)
+      @connection = connection
+      @project_id = project_id
+      @policy_cache = policy_cache
+      @non_custom_claim_keys = %w[
+        aud
+        exp
+        iat
+        iss
+        jti
+        nbf
+        sub
+        active
+        client_id
+        request_id
+        scope
+        status_code
+        token_type
+      ]
+    end
+
+    # Introspects a token JWT from an authorization code response.
+    # Access tokens are JWTs signed with the project's JWKs. Refresh tokens are opaque tokens.
+    # Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+    #
+    # == Parameters:
+    # token::
+    #   The access token (or refresh token) to introspect.
+    #   The type of this field is +String+.
+    # client_id::
+    #   The ID of the client.
+    #   The type of this field is +String+.
+    # client_secret::
+    #   The secret of the client.
+    #   The type of this field is nilable +String+.
+    # token_type_hint::
+    #   A hint on what the token contains. Valid fields are 'access_token' and 'refresh_token'.
+    #   The type of this field is +String+.
+    # authorization_check::
+    #   Optional authorization check object.
+    #   The type of this field is nilable +Hash+.
+    #
+    # == Returns:
+    # An object with the following fields:
+    # subject::
+    #   The subject of the token.
+    #   The type of this field is +String+.
+    # scope::
+    #   The scope of the token.
+    #   The type of this field is +String+.
+    # audience::
+    #   The audience of the token.
+    #   The type of this field is +String+.
+    # expires_at::
+    #   The expiration time of the token.
+    #   The type of this field is +Integer+.
+    # issued_at::
+    #   The issued at time of the token.
+    #   The type of this field is +Integer+.
+    # issuer::
+    #   The issuer of the token.
+    #   The type of this field is +String+.
+    # not_before::
+    #   The not before time of the token.
+    #   The type of this field is +Integer+.
+    # token_type::
+    #   The type of the token.
+    #   The type of this field is +String+.
+    # custom_claims::
+    #   Custom claims in the token.
+    #   The type of this field is +Hash+.
+    def introspect_token_network(
+      token:,
+      client_id:,
+      client_secret: nil,
+      token_type_hint: 'access_token',
+      authorization_check: nil
+    )
+      headers = {}
+      data = {
+        'token' => token,
+        'client_id' => client_id,
+        'token_type_hint' => token_type_hint
+      }
+      data['client_secret'] = client_secret unless client_secret.nil?
+
+      url = @connection.url_prefix + '/v1/oauth2/introspect'
+      res = post_request(url, data, headers)
+
+      jwt_response = res
+      return nil unless jwt_response['active']
+
+      custom_claims = res.reject { |k, _| @non_custom_claim_keys.include?(k) }
+      scope = jwt_response['scope']
+
+      if authorization_check
+        @policy_cache.perform_scope_authorization_check(
+          token_scopes: scope.split,
+          authorization_check: authorization_check
+        )
+      end
+
+      {
+        'subject' => jwt_response['sub'],
+        'scope' => jwt_response['scope'],
+        'audience' => jwt_response['aud'],
+        'expires_at' => jwt_response['exp'],
+        'issued_at' => jwt_response['iat'],
+        'issuer' => jwt_response['iss'],
+        'not_before' => jwt_response['nbf'],
+        'token_type' => jwt_response['token_type'],
+        'custom_claims' => custom_claims
+      }
+    end
+
+    # Introspects a token JWT from an authorization code response.
+    # Access tokens are JWTs signed with the project's JWKs. Refresh tokens are opaque tokens.
+    # Access tokens contain a standard set of claims as well as any custom claims generated from templates.
+    #
+    # == Parameters:
+    # access_token::
+    #   The access token (or refresh token) to introspect.
+    #   The type of this field is +String+.
+    # authorization_check::
+    #   Optional authorization check object.
+    #   The type of this field is nilable +Hash+.
+    #
+    # == Returns:
+    # An object with the following fields:
+    # subject::
+    #   The subject of the token.
+    #   The type of this field is +String+.
+    # scope::
+    #   The scope of the token.
+    #   The type of this field is +String+.
+    # audience::
+    #   The audience of the token.
+    #   The type of this field is +String+.
+    # expires_at::
+    #   The expiration time of the token.
+    #   The type of this field is +Integer+.
+    # issued_at::
+    #   The issued at time of the token.
+    #   The type of this field is +Integer+.
+    # issuer::
+    #   The issuer of the token.
+    #   The type of this field is +String+.
+    # not_before::
+    #   The not before time of the token.
+    #   The type of this field is +Integer+.
+    # token_type::
+    #   The type of the token.
+    #   The type of this field is +String+.
+    # custom_claims::
+    #   Custom claims in the token.
+    #   The type of this field is +Hash+.
+    def introspect_access_token_local(
+      access_token:,
+      authorization_check: nil
+    )
+      scope_claim = 'scope'
+
+      # Create a JWKS loader similar to other classes in the codebase
+      @cache_last_update = 0
+      jwks_loader = lambda do |options|
+        @cached_keys = nil if options[:invalidate] && @cache_last_update < Time.now.to_i - 300
+        if @cached_keys.nil?
+          @cached_keys = get_jwks(project_id: @project_id)
+          @cache_last_update = Time.now.to_i
+        end
+        @cached_keys
+      end
+
+      begin
+        decoded_jwt = JWT.decode(
+          access_token,
+          nil,
+          true,
+          {
+            algorithms: ['RS256'],
+            jwks: jwks_loader,
+            iss: ["stytch.com/#{@project_id}", @connection.url_prefix],
+            aud: @project_id
+          }
+        )[0]
+
+        generic_claims = decoded_jwt
+        custom_claims = generic_claims.reject { |k, _| @non_custom_claim_keys.include?(k) }
+        scope = generic_claims[scope_claim]
+
+        if authorization_check
+          @policy_cache.perform_scope_authorization_check(
+            token_scopes: scope.split,
+            authorization_check: authorization_check
+          )
+        end
+
+        {
+          'subject' => generic_claims['sub'],
+          'scope' => generic_claims[scope_claim],
+          'audience' => generic_claims['aud'],
+          'expires_at' => generic_claims['exp'],
+          'issued_at' => generic_claims['iat'],
+          'issuer' => generic_claims['iss'],
+          'not_before' => generic_claims['nbf'],
+          'token_type' => 'access_token',
+          'custom_claims' => custom_claims
+        }
+      rescue JWT::InvalidIssuerError
+        raise Stytch::JWTInvalidIssuerError
+      rescue JWT::InvalidAudError
+        raise Stytch::JWTInvalidAudienceError
+      rescue JWT::ExpiredSignature
+        raise Stytch::JWTExpiredSignatureError
+      rescue JWT::IncorrectAlgorithm
+        raise Stytch::JWTIncorrectAlgorithmError
+      rescue JWT::DecodeError
+        nil
+      end
+    end
+
+    # Gets the JWKS for the project.
+    #
+    # == Parameters:
+    # project_id::
+    #   The ID of the project.
+    #   The type of this field is +String+.
+    #
+    # == Returns:
+    # The JWKS for the project.
+    #   The type of this field is +Hash+.
+    def get_jwks(project_id:)
+      headers = {}
+      query_params = {}
+      request = request_with_query_params("/v1/sessions/jwks/#{project_id}", query_params)
+      get_request(request, headers)
+    end
+  end
+end

data/lib/stytch/otps.rb

@@ -130,7 +130,7 @@ module Stytch
       # ### Cost to send SMS OTP
       # Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
       #
-      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
       #
       # Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
       #
@@ -212,7 +212,7 @@ module Stytch
       # ### Cost to send SMS OTP
       # Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
       #
-      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via [the API](https://stytch.com/docs/workspace-management/pwa/country-code-allowlist-object), and [add credit card details](https://stytch.com/docs/dashboard/settings/billing) to your account.
+      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.
       #
       # Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
       #

data/lib/stytch/passwords.rb

@@ -408,7 +408,7 @@ module Stytch
       # login_redirect_url::
       #   The URL Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be a route in your application which will run `oauth.authenticate` (see below) and finish the login.
       #
-      #   The URL must be configured as a Login URL in the [Redirect URL page](https://stytch.com/docs/dashboard/redirect-urls). If the field is not specified, the default Login URL will be used.
+      #   The URL must be configured as a Login URL in the [Redirect URL page](https://stytch.com/dashboard/redirect-urls). If the field is not specified, the default Login URL will be used.
       #   The type of this field is nilable +String+.
       # locale::
       #   Used to determine which language to use when sending the user this delivery method. Parameter is a [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`.

data/lib/stytch/rbac.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# !!!
+# WARNING: This file is autogenerated
+# Only modify code within MANUAL() sections
+# or your changes may be overwritten later!
+# !!!
+
+require_relative 'request_helper'
+
+module Stytch
+  class RBAC
+    include Stytch::RequestHelper
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+    # Get the active RBAC Policy for your current Stytch Project. An RBAC Policy is the canonical document that stores all defined Resources and Roles within your RBAC permissioning model.
+    #
+    # When using the backend SDKs, the RBAC Policy will be cached to allow for local evaluations, eliminating the need for an extra request to Stytch.
+    # The policy will be refreshed if an authorization check is requested and the RBAC policy was last updated more than 5 minutes ago.
+    #
+    # Resources and Roles can be created and managed within the [RBAC page](https://stytch.com/dashboard/rbac) in the Dashboard.
+    # Additionally, [Role assignment](https://stytch.com/docs/guides/rbac/role-assignment) can be programmatically managed through certain Stytch API endpoints.
+    #
+    # Check out the [RBAC overview](https://stytch.com/docs/guides/rbac/overview) to learn more about Stytch's RBAC permissioning model.
+    #
+    # == Parameters:
+    #
+    # == Returns:
+    # An object with the following fields:
+    # request_id::
+    #   Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+    #   The type of this field is +String+.
+    # status_code::
+    #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
+    #   The type of this field is +Integer+.
+    # policy::
+    #   The RBAC Policy document that contains all defined Roles and Resources – which are managed in the [Dashboard](https://stytch.com/dashboard/rbac). Read more about these entities and how they work in our [RBAC overview](https://stytch.com/docs/guides/rbac/overview).
+    #   The type of this field is nilable +Policy+ (+object+).
+    def policy
+      headers = {}
+      query_params = {}
+      request = request_with_query_params('/v1/rbac/policy', query_params)
+      get_request(request, headers)
+    end
+  end
+end

data/lib/stytch/rbac_local.rb

@@ -3,7 +3,7 @@
 require_relative 'errors'
 require_relative 'request_helper'
 
-module StytchB2B
+module Stytch
   class PolicyCache
     def initialize(rbac_client:)
       @rbac_client = rbac_client
@@ -31,8 +31,7 @@ module StytchB2B
       subject_org_id:,
       authorization_check:
     )
-      request_org_id = authorization_check['organization_id']
-      raise Stytch::TenancyError.new(subject_org_id, request_org_id) if request_org_id != subject_org_id
+      raise Stytch::TenancyError.new(subject_org_id, authorization_check['organization_id']) if subject_org_id != authorization_check['organization_id']
 
       policy = get_policy
 
@@ -54,5 +53,69 @@ module StytchB2B
       # If we get here, we didn't find a matching permission
       raise Stytch::PermissionError, authorization_check
     end
+
+    # Performs an authorization check against the project's policy and a set of roles. If the
+    # check succeeds, this method will return. If the check fails, a PermissionError
+    # will be raised. This is used for role based authorization.
+    def perform_consumer_authorization_check(
+      subject_roles:,
+      authorization_check:
+    )
+      policy = get_policy
+
+      # For consumer authorization, we check roles without tenancy validation
+      for role in policy['roles']
+        next unless subject_roles.include?(role['role_id'])
+
+        for permission in role['permissions']
+          actions = permission['actions']
+          resource = permission['resource_id']
+          has_matching_action = actions.include?('*') || actions.include?(authorization_check['action'])
+          has_matching_resource = resource == authorization_check['resource_id']
+          if has_matching_action && has_matching_resource
+            return # Permission granted
+          end
+        end
+      end
+
+      # If we get here, we didn't find a matching permission
+      raise Stytch::PermissionError, authorization_check
+    end
+
+    # Performs an authorization check against the project's policy and a set of scopes. If the
+    # check succeeds, this method will return. If the check fails, a PermissionError
+    # will be raised. This is used for OAuth-style scope-based authorization.
+    # authorization_check is an object with keys 'action' and 'resource_id'
+    def perform_scope_authorization_check(
+      token_scopes:,
+      authorization_check:
+    )
+      policy = get_policy
+
+      # For scope-based authorization, we check if any of the token scopes match policy scopes
+      # and if those scopes grant permission for the requested action/resource
+      action = authorization_check['action']
+      resource_id = authorization_check['resource_id']
+
+      # Check if any of the token scopes grant permission for this action/resource
+      for scope_obj in policy['scopes']
+        scope_name = scope_obj['scope']
+        next unless token_scopes.include?(scope_name)
+
+        # Check if this scope grants permission for the requested action/resource
+        for permission in scope_obj['permissions']
+          actions = permission['actions']
+          resource = permission['resource_id']
+          has_matching_action = actions.include?('*') || actions.include?(action)
+          has_matching_resource = resource == resource_id
+          if has_matching_action && has_matching_resource
+            return # Permission granted
+          end
+        end
+      end
+
+      # If we get here, we didn't find a matching permission
+      raise Stytch::PermissionError, authorization_check
+    end
   end
 end

data/lib/stytch/sessions.rb

@@ -15,9 +15,10 @@ module Stytch
   class Sessions
     include Stytch::RequestHelper
 
-    def initialize(connection, project_id)
+    def initialize(connection, project_id, policy_cache)
       @connection = connection
 
+      @policy_cache = policy_cache
       @project_id = project_id
       @cache_last_update = 0
       @jwks_loader = lambda do |options|
@@ -81,6 +82,13 @@ module Stytch
     #
     #   Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
     #   The type of this field is nilable +object+.
+    # authorization_check::
+    #   If an `authorization_check` object is passed in, this endpoint will also check if the User is
+    #   authorized to perform the given action on the given Resource. A User is authorized if they are assigned a Role with adequate permissions.
+    #
+    #   If the User is not authorized to perform the specified action on the specified Resource, a 403 error will be thrown.
+    #   Otherwise, the response will contain a list of Roles that satisfied the authorization check.
+    #   The type of this field is nilable +AuthorizationCheck+ (+object+).
     #
     # == Returns:
     # An object with the following fields:
@@ -105,11 +113,16 @@ module Stytch
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
+    # verdict::
+    #   If an `authorization_check` is provided in the request and the check succeeds, this field will return
+    #   information about why the User was granted permission.
+    #   The type of this field is nilable +AuthorizationVerdict+ (+object+).
     def authenticate(
       session_token: nil,
       session_duration_minutes: nil,
       session_jwt: nil,
-      session_custom_claims: nil
+      session_custom_claims: nil,
+      authorization_check: nil
     )
       headers = {}
       request = {}
@@ -117,6 +130,7 @@ module Stytch
       request[:session_duration_minutes] = session_duration_minutes unless session_duration_minutes.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
+      request[:authorization_check] = authorization_check unless authorization_check.nil?
 
       post_request('/v1/sessions/authenticate', request, headers)
     end
@@ -156,7 +170,7 @@ module Stytch
       post_request('/v1/sessions/revoke', request, headers)
     end
 
-    # Migrate a session from an external OIDC compliant endpoint. Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the [Dashboard](https://stytch.com/docs/dashboard), and then perform a lookup using the `session_token`. If the response contains a valid email address, Stytch will attempt to match that email address with an existing User and create a Stytch Session. You will need to create the user before using this endpoint.
+    # Migrate a session from an external OIDC compliant endpoint. Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the [Dashboard](https://stytch.com/dashboard), and then perform a lookup using the `session_token`. If the response contains a valid email address, Stytch will attempt to match that email address with an existing User and create a Stytch Session. You will need to create the user before using this endpoint.
     #
     # == Parameters:
     # session_token::
@@ -326,7 +340,7 @@ module Stytch
       get_request(request, headers)
     end
 
-    # Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens). If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
+    # Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/dashboard/trusted-auth-tokens). If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
     #
     # == Parameters:
     # profile_id::
@@ -421,7 +435,8 @@ module Stytch
       max_token_age_seconds: nil,
       session_duration_minutes: nil,
       session_custom_claims: nil,
-      clock_tolerance_seconds: nil
+      clock_tolerance_seconds: nil,
+      authorization_check: nil
     )
       max_token_age_seconds = 300 if max_token_age_seconds.nil?
       clock_tolerance_seconds = 0 if clock_tolerance_seconds.nil?
@@ -430,28 +445,32 @@ module Stytch
         return authenticate(
           session_jwt: session_jwt,
           session_duration_minutes: session_duration_minutes,
-          session_custom_claims: session_custom_claims
+          session_custom_claims: session_custom_claims,
+          authorization_check: authorization_check
         )
       end
 
       session = authenticate_jwt_local(
         session_jwt,
         max_token_age_seconds: max_token_age_seconds,
-        clock_tolerance_seconds: clock_tolerance_seconds
+        clock_tolerance_seconds: clock_tolerance_seconds,
+        authorization_check: authorization_check
       )
       return session unless session.nil?
 
       authenticate(
         session_jwt: session_jwt,
         session_duration_minutes: session_duration_minutes,
-        session_custom_claims: session_custom_claims
+        session_custom_claims: session_custom_claims,
+        authorization_check: authorization_check
       )
     rescue StandardError
       # JWT could not be verified locally. Check with the Stytch API.
       authenticate(
         session_jwt: session_jwt,
         session_duration_minutes: session_duration_minutes,
-        session_custom_claims: session_custom_claims
+        session_custom_claims: session_custom_claims,
+        authorization_check: authorization_check
       )
     end
 
@@ -461,7 +480,7 @@ module Stytch
     # This method never authenticates a JWT directly with the API
     # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
     # If clock_tolerance_seconds is not supplied 0 seconds will be used as the default.
-    def authenticate_jwt_local(session_jwt, max_token_age_seconds: nil, clock_tolerance_seconds: nil)
+    def authenticate_jwt_local(session_jwt, max_token_age_seconds: nil, clock_tolerance_seconds: nil, authorization_check: nil)
       max_token_age_seconds = 300 if max_token_age_seconds.nil?
       clock_tolerance_seconds = 0 if clock_tolerance_seconds.nil?
 
@@ -488,6 +507,14 @@ module Stytch
         raise JWTIncorrectAlgorithmError
       end
 
+      # Do the auth check - intentionally don't rescue errors from here
+      if authorization_check
+        @policy_cache.perform_consumer_authorization_check(
+          subject_roles: session['roles'],
+          authorization_check: authorization_check
+        )
+      end
+
       session
     end
 

data/lib/stytch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stytch
-  VERSION = '10.25.0'
+  VERSION = '10.26.0'
 end

data/lib/stytch.rb

@@ -4,6 +4,7 @@ require 'faraday'
 
 require_relative 'stytch/b2b_client'
 require_relative 'stytch/client'
+require_relative 'stytch/idp'
 require_relative 'stytch/method_options'
 require_relative 'stytch/middleware'
 require_relative 'stytch/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stytch
 version: !ruby/object:Gem::Version
-  version: 10.25.0
+  version: 10.26.0
 platform: ruby
 authors:
 - stytch
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2025-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -126,6 +126,7 @@ files:
 - lib/stytch.rb
 - lib/stytch/b2b_client.rb
 - lib/stytch/b2b_discovery.rb
+- lib/stytch/b2b_idp.rb
 - lib/stytch/b2b_impersonation.rb
 - lib/stytch/b2b_magic_links.rb
 - lib/stytch/b2b_oauth.rb
@@ -143,6 +144,7 @@ files:
 - lib/stytch/crypto_wallets.rb
 - lib/stytch/errors.rb
 - lib/stytch/fraud.rb
+- lib/stytch/idp.rb
 - lib/stytch/impersonation.rb
 - lib/stytch/m2m.rb
 - lib/stytch/magic_links.rb
@@ -152,6 +154,7 @@ files:
 - lib/stytch/otps.rb
 - lib/stytch/passwords.rb
 - lib/stytch/project.rb
+- lib/stytch/rbac.rb
 - lib/stytch/rbac_local.rb
 - lib/stytch/request_helper.rb
 - lib/stytch/sessions.rb