stytch 6.6.0 → 7.0.0

data/lib/stytch/b2b_otp.rb

@@ -84,6 +84,7 @@ module StytchB2B
         mfa_phone_number: nil,
         locale: nil
       )
+        headers = {}
         request = {
           organization_id: organization_id,
           member_id: member_id
@@ -91,7 +92,7 @@ module StytchB2B
         request[:mfa_phone_number] = mfa_phone_number unless mfa_phone_number.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/b2b/otps/sms/send', request)
+        post_request('/v1/b2b/otps/sms/send', request, headers)
       end
 
       # SMS OTPs may not be used as a primary authentication mechanism. They can be used to complete an MFA requirement, or they can be used as a step-up factor to be added to an existing session.
@@ -197,6 +198,7 @@ module StytchB2B
         session_custom_claims: nil,
         set_mfa_enrollment: nil
       )
+        headers = {}
         request = {
           organization_id: organization_id,
           member_id: member_id,
@@ -209,7 +211,7 @@ module StytchB2B
         request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
         request[:set_mfa_enrollment] = set_mfa_enrollment unless set_mfa_enrollment.nil?
 
-        post_request('/v1/b2b/otps/sms/authenticate', request)
+        post_request('/v1/b2b/otps/sms/authenticate', request, headers)
       end
     end
   end

data/lib/stytch/b2b_passwords.rb

@@ -78,12 +78,13 @@ module StytchB2B
       password:,
       email_address: nil
     )
+      headers = {}
       request = {
         password: password
       }
       request[:email_address] = email_address unless email_address.nil?
 
-      post_request('/v1/b2b/passwords/strength_check', request)
+      post_request('/v1/b2b/passwords/strength_check', request, headers)
     end
 
     # Adds an existing password to a member's email that doesn't have a password yet. We support migrating members from passwords stored with bcrypt, scrypt, argon2, MD-5, SHA-1, and PBKDF2. This endpoint has a rate limit of 100 requests per second.
@@ -101,6 +102,11 @@ module StytchB2B
     # 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.
     #   The type of this field is +String+.
+    # preserve_existing_sessions::
+    #   (Coming Soon) Whether to preserve existing sessions when explicit Roles that are revoked are also implicitly assigned
+    #   by SSO connection or SSO group. Defaults to `false` - that is, existing Member Sessions that contain SSO
+    #   authentication factors with the affected SSO connection IDs will be revoked.
+    #   The type of this field is +Boolean+.
     # md_5_config::
     #   Optional parameters for MD-5 hash types.
     #   The type of this field is nilable +MD5Config+ (+object+).
@@ -127,6 +133,16 @@ module StytchB2B
     #   frontend SDK, and should not be used to store critical information. See the [Metadata resource](https://stytch.com/docs/b2b/api/metadata)
     #   for complete field behavior details.
     #   The type of this field is nilable +object+.
+    # roles::
+    #   (Coming Soon) Roles to explicitly assign to this Member.
+    #  Will completely replace any existing explicitly assigned roles. See the
+    #  [RBAC guide](https://stytch.com/docs/b2b/guides/rbac/role-assignment) for more information about role assignment.
+    #
+    #    If a Role is removed from a Member, and the Member is also implicitly assigned this Role from an SSO connection
+    #    or an SSO group, we will by default revoke any existing sessions for the Member that contain any SSO
+    #    authentication factors with the affected connection ID. You can preserve these sessions by passing in the
+    #    `preserve_existing_sessions` parameter with a value of `true`.
+    #   The type of this field is nilable list of +String+.
     #
     # == Returns:
     # An object with the following fields:
@@ -153,6 +169,7 @@ module StytchB2B
       hash:,
       hash_type:,
       organization_id:,
+      preserve_existing_sessions:,
       md_5_config: nil,
       argon_2_config: nil,
       sha_1_config: nil,
@@ -160,13 +177,16 @@ module StytchB2B
       pbkdf_2_config: nil,
       name: nil,
       trusted_metadata: nil,
-      untrusted_metadata: nil
+      untrusted_metadata: nil,
+      roles: nil
     )
+      headers = {}
       request = {
         email_address: email_address,
         hash: hash,
         hash_type: hash_type,
-        organization_id: organization_id
+        organization_id: organization_id,
+        preserve_existing_sessions: preserve_existing_sessions
       }
       request[:md_5_config] = md_5_config unless md_5_config.nil?
       request[:argon_2_config] = argon_2_config unless argon_2_config.nil?
@@ -176,8 +196,9 @@ module StytchB2B
       request[:name] = name unless name.nil?
       request[:trusted_metadata] = trusted_metadata unless trusted_metadata.nil?
       request[:untrusted_metadata] = untrusted_metadata unless untrusted_metadata.nil?
+      request[:roles] = roles unless roles.nil?
 
-      post_request('/v1/b2b/passwords/migrate', request)
+      post_request('/v1/b2b/passwords/migrate', request, headers)
     end
 
     # Authenticate a member with their email address and password. This endpoint verifies that the member has a password currently set, and that the entered password is correct.
@@ -285,6 +306,7 @@ module StytchB2B
       session_custom_claims: nil,
       locale: nil
     )
+      headers = {}
       request = {
         organization_id: organization_id,
         email_address: email_address,
@@ -296,7 +318,7 @@ module StytchB2B
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
       request[:locale] = locale unless locale.nil?
 
-      post_request('/v1/b2b/passwords/authenticate', request)
+      post_request('/v1/b2b/passwords/authenticate', request, headers)
     end
 
     class Email
@@ -374,6 +396,7 @@ module StytchB2B
         locale: nil,
         reset_password_template_id: nil
       )
+        headers = {}
         request = {
           organization_id: organization_id,
           email_address: email_address
@@ -385,7 +408,7 @@ module StytchB2B
         request[:locale] = locale unless locale.nil?
         request[:reset_password_template_id] = reset_password_template_id unless reset_password_template_id.nil?
 
-        post_request('/v1/b2b/passwords/email/reset/start', request)
+        post_request('/v1/b2b/passwords/email/reset/start', request, headers)
       end
 
       # Reset the member's password and authenticate them. This endpoint checks that the password reset token is valid, hasn’t expired, or already been used.
@@ -500,6 +523,7 @@ module StytchB2B
         session_custom_claims: nil,
         locale: nil
       )
+        headers = {}
         request = {
           password_reset_token: password_reset_token,
           password: password
@@ -511,7 +535,7 @@ module StytchB2B
         request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/b2b/passwords/email/reset', request)
+        post_request('/v1/b2b/passwords/email/reset', request, headers)
       end
     end
 
@@ -611,6 +635,7 @@ module StytchB2B
         session_custom_claims: nil,
         locale: nil
       )
+        headers = {}
         request = {
           organization_id: organization_id,
           password: password
@@ -621,7 +646,7 @@ module StytchB2B
         request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/b2b/passwords/session/reset', request)
+        post_request('/v1/b2b/passwords/session/reset', request, headers)
       end
     end
 
@@ -742,6 +767,7 @@ module StytchB2B
         session_custom_claims: nil,
         locale: nil
       )
+        headers = {}
         request = {
           email_address: email_address,
           existing_password: existing_password,
@@ -754,7 +780,7 @@ module StytchB2B
         request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/b2b/passwords/existing_password/reset', request)
+        post_request('/v1/b2b/passwords/existing_password/reset', request, headers)
       end
     end
   end

data/lib/stytch/b2b_rbac.rb

@@ -0,0 +1,48 @@
+# 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 StytchB2B
+  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 automatically be loaded and refreshed in the background to allow for local evaluations, eliminating the need for an extra request to Stytch.
+    #
+    # Resources and Roles can be created and managed within the [Dashboard](/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 or [contact us](https://share.hsforms.com/1qkU__-1CT1--lnqRDxphXgd4bkb) to request early access.
+    #
+    # == 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](/dashboard). 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 = {}
+      query_params = {}
+      request = request_with_query_params('/v1/b2b/rbac/policy', query_params)
+      get_request(request, headers)
+    end
+  end
+end

data/lib/stytch/b2b_sessions.rb

@@ -15,9 +15,10 @@ module StytchB2B
   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|
@@ -58,18 +59,26 @@ module StytchB2B
       organization_id:,
       member_id:
     )
+      headers = {}
       query_params = {
         organization_id: organization_id,
         member_id: member_id
       }
       request = request_with_query_params('/v1/b2b/sessions', query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
     # Authenticates a Session and updates its lifetime by the specified `session_duration_minutes`. If the `session_duration_minutes` is not specified, a Session will not be extended. This endpoint requires either a `session_jwt` or `session_token` be included in the request. It will return an error if both are present.
     #
     # You may provide a JWT that needs to be refreshed and is expired according to its `exp` claim. A new JWT will be returned if both the signature and the underlying Session are still valid.
     #
+    # If an `authorization_check` object is passed in, this method will also check if the Member is authorized to perform the given action on the given Resource in the specified Organization. A Member is authorized if their Member Session contains a Role, assigned [explicitly or implicitly](https://github.com/docs/b2b/guides/rbac/role-assignment), with adequate permissions.
+    # In addition, the `organization_id` passed in the authorization check must match the Member's Organization.
+    #
+    # If the Member is not authorized to perform the specified action on the specified Resource, or if the
+    # `organization_id` does not match the Member's Organization, a 403 error will be thrown.
+    # Otherwise, the response will contain a list of Roles that satisfied the authorization check.
+    #
     # == Parameters:
     # session_token::
     #   A secret token for a given Stytch Session.
@@ -95,6 +104,21 @@ module StytchB2B
     #   delete a key, supply a null value. 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::
+    #   (Coming Soon) If an `authorization_check` object is passed in, this endpoint will also check if the Member is
+    #   authorized to perform the given action on the given Resource in the specified Organization. A Member is authorized if
+    #   their Member Session contains a Role, assigned
+    #   [explicitly or implicitly](https://github.com/docs/b2b/guides/rbac/role-assignment), with adequate permissions.
+    #   In addition, the `organization_id` passed in the authorization check must match the Member's Organization.
+    #
+    #   The Roles on the Member Session may differ from the Roles you see on the Member object - Roles that are implicitly
+    #   assigned by SSO connection or SSO group will only be valid for a Member Session if there is at least one authentication
+    #   factor on the Member Session from the specified SSO connection.
+    #
+    #   If the Member is not authorized to perform the specified action on the specified Resource, or if the
+    #   `organization_id` does not match the Member's Organization, 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:
@@ -119,19 +143,26 @@ module StytchB2B
     # 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::
+    #   (Coming Soon) 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.
+    #   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 = {}
       request[:session_token] = session_token unless session_token.nil?
       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/b2b/sessions/authenticate', request)
+      post_request('/v1/b2b/sessions/authenticate', request, headers)
     end
 
     # Revoke a Session and immediately invalidate all its tokens. To revoke a specific Session, pass either the `member_session_id`, `session_token`, or `session_jwt`. To revoke all Sessions for a Member, pass the `member_id`.
@@ -164,13 +195,14 @@ module StytchB2B
       session_jwt: nil,
       member_id: nil
     )
+      headers = {}
       request = {}
       request[:member_session_id] = member_session_id unless member_session_id.nil?
       request[:session_token] = session_token unless session_token.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:member_id] = member_id unless member_id.nil?
 
-      post_request('/v1/b2b/sessions/revoke', request)
+      post_request('/v1/b2b/sessions/revoke', request, headers)
     end
 
     # Use this endpoint to exchange a Member's existing session for another session in a different Organization. This can be used to accept an invite, but not to create a new member via domain matching.
@@ -270,6 +302,7 @@ module StytchB2B
       session_custom_claims: nil,
       locale: nil
     )
+      headers = {}
       request = {
         organization_id: organization_id
       }
@@ -279,7 +312,7 @@ module StytchB2B
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
       request[:locale] = locale unless locale.nil?
 
-      post_request('/v1/b2b/sessions/exchange', request)
+      post_request('/v1/b2b/sessions/exchange', request, headers)
     end
 
     # Get the JSON Web Key Set (JWKS) for a project.
@@ -311,9 +344,10 @@ module StytchB2B
     def get_jwks(
       project_id:
     )
+      headers = {}
       query_params = {}
       request = request_with_query_params("/v1/b2b/sessions/jwks/#{project_id}", query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
     # MANUAL(Sessions::authenticate_jwt)(SERVICE_METHOD)
@@ -325,38 +359,43 @@ module StytchB2B
     # If max_token_age_seconds is set and the JWT was issued (based on the "iat" claim) less than
     # max_token_age_seconds seconds ago, then just verify locally and don't call the API
     # To force remote validation for all tokens, set max_token_age_seconds to 0 or call authenticate()
+    # Note that the 'user_id' field of the returned session is DEPRECATED: Use member_id instead
+    # This field will be removed in a future MAJOR release.
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
     def authenticate_jwt(
       session_jwt,
       max_token_age_seconds: nil,
       session_duration_minutes: nil,
-      session_custom_claims: nil
+      session_custom_claims: nil,
+      authorization_check: nil
     )
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
       if max_token_age_seconds == 0
         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
 
-      decoded_jwt = authenticate_jwt_local(session_jwt)
-      iat_time = Time.at(decoded_jwt['iat']).to_datetime
-      if iat_time + max_token_age_seconds >= Time.now
-        session = marshal_jwt_into_session(decoded_jwt)
-        { 'session' => session }
-      else
-        authenticate(
-          session_jwt: session_jwt,
-          session_duration_minutes: session_duration_minutes,
-          session_custom_claims: session_custom_claims
-        )
-      end
+      decoded_jwt = authenticate_jwt_local(session_jwt: session_jwt, authorization_check: authorization_check)
+      return decoded_jwt unless decoded_jwt.nil?
+
+      authenticate(
+        session_jwt: session_jwt,
+        session_duration_minutes: session_duration_minutes,
+        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
 
@@ -364,41 +403,70 @@ module StytchB2B
     # Uses the cached value to get the JWK but if it is unavailable, it calls the get_jwks()
     # function to get the JWK
     # This method never authenticates a JWT directly with the API
-    def authenticate_jwt_local(session_jwt)
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
+    def authenticate_jwt_local(session_jwt, max_token_age_seconds: nil, authorization_check: nil)
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
       issuer = 'stytch.com/' + @project_id
       begin
         decoded_token = JWT.decode session_jwt, nil, true,
                                    { jwks: @jwks_loader, iss: issuer, verify_iss: true, aud: @project_id, verify_aud: true, algorithms: ['RS256'] }
-        decoded_token[0]
+
+        session = decoded_token[0]
+        iat_time = Time.at(session['iat']).to_datetime
+        return nil unless iat_time + max_token_age_seconds >= Time.now
+
+        session = marshal_jwt_into_session(session)
       rescue JWT::InvalidIssuerError
-        raise JWTInvalidIssuerError
+        raise Stytch::JWTInvalidIssuerError
       rescue JWT::InvalidAudError
-        raise JWTInvalidAudienceError
+        raise Stytch::JWTInvalidAudienceError
       rescue JWT::ExpiredSignature
-        raise JWTExpiredSignatureError
+        raise Stytch::JWTExpiredSignatureError
       rescue JWT::IncorrectAlgorithm
-        raise JWTIncorrectAlgorithmError
+        raise Stytch::JWTIncorrectAlgorithmError
+      end
+
+      # Do the auth check - intentionally don't rescue errors from here
+      if authorization_check && session['roles']
+        @policy_cache.perform_authorization_check(
+          subject_roles: session['roles'],
+          subject_org_id: session['member_session']['organization_id'],
+          authorization_check: authorization_check
+        )
       end
+
+      session
     end
 
+    # Note that the 'user_id' field is DEPRECATED: Use member_id instead
+    # This field will be removed in a future MAJOR release.
     def marshal_jwt_into_session(jwt)
       stytch_claim = 'https://stytch.com/session'
+      organization_claim = 'https://stytch.com/organization'
+
       expires_at = jwt[stytch_claim]['expires_at'] || Time.at(jwt['exp']).to_datetime.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
       # The custom claim set is all the claims in the payload except for the standard claims and
       # the Stytch session claim. The cleanest way to collect those seems to be naming what we want
       # to omit and filtering the rest to collect the custom claims.
-      reserved_claims = ['aud', 'exp', 'iat', 'iss', 'jti', 'nbf', 'sub', stytch_claim]
+      reserved_claims = ['aud', 'exp', 'iat', 'iss', 'jti', 'nbf', 'sub', stytch_claim, organization_claim]
       custom_claims = jwt.reject { |key, _| reserved_claims.include?(key) }
       {
-        'session_id' => jwt[stytch_claim]['id'],
-        'user_id' => jwt['sub'],
-        'started_at' => jwt[stytch_claim]['started_at'],
-        'last_accessed_at' => jwt[stytch_claim]['last_accessed_at'],
-        # For JWTs that include it, prefer the inner expires_at claim.
-        'expires_at' => expires_at,
-        'attributes' => jwt[stytch_claim]['attributes'],
-        'authentication_factors' => jwt[stytch_claim]['authentication_factors'],
-        'custom_claims' => custom_claims
+        'member_session' => {
+          'session_id' => jwt[stytch_claim]['id'],
+          'organization_id' => jwt[organization_claim]['organization_id'],
+          'member_id' => jwt['sub'],
+          # DEPRECATED: Use member_id instead
+          'user_id' => jwt['sub'],
+          'started_at' => jwt[stytch_claim]['started_at'],
+          'last_accessed_at' => jwt[stytch_claim]['last_accessed_at'],
+          # For JWTs that include it, prefer the inner expires_at claim.
+          'expires_at' => expires_at,
+          'attributes' => jwt[stytch_claim]['attributes'],
+          'authentication_factors' => jwt[stytch_claim]['authentication_factors'],
+          'custom_claims' => custom_claims
+        },
+        'roles' => jwt[stytch_claim]['roles']
       }
     end
     # ENDMANUAL(Sessions::authenticate_jwt)