strongmind-platform-sdk 3.32.0 → 3.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 999f26d4cd8d102f6dc1016bff6c6c209852c54e69ab1dc14b4768264f248f5c
-  data.tar.gz: e276aa457755f6d60729f29bdc7255d79561a8dd4582fad39c57593aaebb13c7
+  metadata.gz: 7b23cd42819001403fdf176b48df36e0d0acd9fd65a625e24a65899ba3496715
+  data.tar.gz: aa7316e0ef335e0cbc423ae5b9f201b6e076d971373966b60e2db229f9b86fc4
 SHA512:
-  metadata.gz: db42e98d0b0769986f4f495a4f08b8f0b37904b90abf2d66e5e4e6d91f80a307048b684f546efa0f83bab209d266b2ed086f244ade5114cd93f36aa44196cbcb
-  data.tar.gz: 98ce988fa4fd168449b2dce2368fd6f6ef669557bd7df3489fc334e94c70e0874e20ad8267836f08978ff2969ff2ae7e2b19fcbf93d941d67a950809dee89d4a
+  metadata.gz: d45af1a0c4478d1310763cf3dd33effe6a96fdc6f76ab1dcbcf15fc710a7ad618d82515ec32d9ed65b4ac520c64d1c6722ba1614c57bf56b77823e003d45641a
+  data.tar.gz: 3655fa57a8e56e9e31b8b2aa9c40abca15abe7ed7f35c512a31585992c4cbd985e2aef3884e429c76f6362ca4c83c517389089eb7c86084764abe9f121fe931c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [3.33.0] - 2026-07-28
+
+- Add `PlatformSdk::Identity::Zitadel::Client` — Zitadel v2 user API client (`#provision_identity`), mirroring the IS4 client's signature. Preserves the IS4 `Id` as the Zitadel `userId` and treats a `409` as an idempotent replay once the preserved id is confirmed to hold the same username.
+- Add `PlatformSdk::Identity::Zitadel::AuthClient` — fetches and caches machine-user access tokens via `client_credentials`, thread-safe under concurrent callers. `Zitadel::Client` takes any token-provider object responding to `#auth_token` (a seam for wrapping `AuthClient`, e.g. behind `Rails.cache`). `AuthClient` accepts a `scope:` keyword (defaults to the management-API audience) and exposes `#expires_at`.
+- Add `PlatformSdk::Identity::Zitadel::UserPayload.from_is4` — maps the IS4 `WithProfile` payload shape onto Zitadel's `AddHumanUser` request, dropping password/reset-email fields (SIS creations are always shells) and marking email/phone unverified.
+- Redact `client_secret`/bearer-token values from the raised error payload in `ErrorHandleable#raise_error_with_payload`, not just the logged line, since the exception itself is handed to consumer instrumentation.
+
 ## [3.32.0] - 2026-06-10
 
 - Add `PlatformSdk::LlmGateway::Client#generate_offline_activity` — posts to `POST /activities/generate` with `learning_component`, `learning_objective`, and `grade_level` and returns the parsed response body.

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    strongmind-platform-sdk (3.32.0)
+    strongmind-platform-sdk (3.33.0)
       asset_sync
       aws-sdk-cloudwatch
       aws-sdk-secretsmanager (~> 1.66)
+      base64
       faraday (~> 2.5, >= 2.5.2)
       faraday-retry
       fog-aws
@@ -124,7 +125,7 @@ GEM
     base64 (0.2.0)
     bigdecimal (3.1.8)
     builder (3.3.0)
-    cgi (0.5.1)
+    cgi (0.5.2)
     coderay (1.1.3)
     concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
@@ -138,7 +139,7 @@ GEM
     erubi (1.13.0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
-    excon (1.5.0)
+    excon (1.6.0)
       logger
     factory_bot (6.4.6)
       activesupport (>= 5.0.0)
@@ -152,6 +153,7 @@ GEM
     faraday-retry (2.2.1)
       faraday (~> 2.0)
     ffi (1.17.0)
+    ffi (1.17.0-arm64-darwin)
     ffi (1.17.0-x86_64-darwin)
     ffi (1.17.0-x86_64-linux-gnu)
     fog-aws (3.33.2)
@@ -172,11 +174,14 @@ GEM
       nokogiri (>= 1.5.11, < 2.0.0)
     formatador (1.2.3)
       reline
-    globalid (1.3.0)
+    globalid (1.4.0)
       activesupport (>= 6.1)
     google-protobuf (4.33.6)
       bigdecimal
       rake (>= 13)
+    google-protobuf (4.33.6-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
     google-protobuf (4.33.6-x86_64-darwin)
       bigdecimal
       rake (>= 13)
@@ -202,7 +207,7 @@ GEM
     loofah (2.22.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    mail (2.9.0)
+    mail (2.9.1)
       logger
       mini_mime (>= 0.1.1)
       net-imap
@@ -213,7 +218,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2026.0414)
+    mime-types-data (3.2026.0701)
     mini_mime (1.1.5)
     mini_portile2 (2.8.7)
     minitest (5.24.1)
@@ -221,7 +226,7 @@ GEM
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri
-    net-imap (0.6.4.1)
+    net-imap (0.6.6)
       date
       net-protocol
     net-pop (0.1.2)
@@ -231,12 +236,14 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.5)
-    nokogiri (1.16.7)
+    nokogiri (1.19.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.16.7-x86_64-darwin)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.7-x86_64-linux)
+    nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
     opentelemetry-api (1.8.0)
       logger
@@ -363,6 +370,7 @@ GEM
       redis-client (>= 0.22.2)
     sqlite3 (1.7.3)
       mini_portile2 (~> 2.8.0)
+    sqlite3 (1.7.3-arm64-darwin)
     sqlite3 (1.7.3-x86_64-darwin)
     sqlite3 (1.7.3-x86_64-linux)
     stringio (3.1.1)
@@ -390,13 +398,14 @@ GEM
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
     webrick (1.8.1)
-    websocket-driver (0.8.1)
+    websocket-driver (0.8.2)
       base64
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     zeitwerk (2.6.17)
 
 PLATFORMS
+  arm64-darwin
   ruby
   x86_64-darwin-21
   x86_64-linux

data/lib/platform_sdk/canvas_api/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "platform_sdk/version"
 
 module PlatformSdk
   module CanvasApiWrapper
@@ -15,7 +16,13 @@ module PlatformSdk
       def initialize(domain:, token:)
         @host = "https://#{domain}"
         @token = token
-        @connection = Faraday.new(url: host, headers: { 'Authorization' => "Bearer #{token}" })
+        @connection = Faraday.new(
+          url: host,
+          headers: {
+            'Authorization' => "Bearer #{token}",
+            'User-Agent' => "StrongMind-PlatformSDK/#{PlatformSdk::VERSION}"
+          }
+        )
       end
 
       # @param course_id [Integer]

data/lib/platform_sdk/identity/error_handleable.rb

@@ -4,6 +4,13 @@ module PlatformSdk
   module Identity
     # Error handling for Identity SDK
     module ErrorHandleable
+      # The logged payload is the raw request body, which for token endpoints
+      # carries client credentials; redact those fields (form-encoded and
+      # JSON shapes) so an auth outage can't write secrets to consumer logs.
+      SENSITIVE_KEYS = 'client_secret|client_assertion|refresh_token|password'
+      FORM_SECRET_PATTERN = /(#{SENSITIVE_KEYS})=[^&]*/i
+      JSON_SECRET_PATTERN = /("(?:#{SENSITIVE_KEYS})"\s*:\s*")[^"]*(")/i
+
       def with_rescue
         yield
       rescue Faraday::TimeoutError => e
@@ -15,14 +22,62 @@ module PlatformSdk
       end
 
       def raise_error_with_payload(exception_class, error)
-        json_log = {
-          exception: exception_class.new.class.name.demodulize,
-          payload: error.response.dig(:request, :body),
+        Rails.logger.info(error_log_payload(exception_class, error).to_json) if defined?(Rails)
+        # The exception itself carries error.response on to consumer
+        # instrumentation (Sentry, custom error handlers), so the raw
+        # request body/headers - which can hold a client_secret or bearer
+        # token - must be scrubbed here too, not just in the log line above.
+        raise exception_class, scrub_response(error.response)
+      end
+
+      # No ActiveSupport here (String#demodulize): this must work for
+      # non-Rails consumers, where the log line is skipped but this hash is
+      # still built.
+      def error_log_payload(exception_class, error)
+        {
+          exception: exception_class.name.split('::').last,
+          payload: scrub_secrets(error.response.dig(:request, :body)),
           response_body: error.response[:body],
           status: error.response[:status]
         }.compact
-        Rails.logger.info json_log.to_json if defined?(Rails)
-        raise exception_class, error.response
+      end
+
+      def scrub_secrets(body)
+        return body unless body.is_a?(String)
+
+        body.gsub(FORM_SECRET_PATTERN) { "#{Regexp.last_match(1)}=[REDACTED]" }
+            .gsub(JSON_SECRET_PATTERN, '\1[REDACTED]\2')
+      end
+
+      # Returns a scrubbed copy of the Faraday error response hash; the
+      # original (and its nested :request hash) are left untouched. Only
+      # [:request][:body] and [:request][:headers] are touched -
+      # [:status] and [:body] (the response body) are read elsewhere
+      # (e.g. e.response&.dig(:status), e.response&.dig(:body, 'paramName'))
+      # and must reach consumers unchanged.
+      def scrub_response(response)
+        return response unless response.is_a?(Hash)
+
+        scrubbed = response.dup
+        scrubbed[:request] = scrub_request(response[:request]) if response[:request].is_a?(Hash)
+        scrubbed
+      end
+
+      def scrub_request(request)
+        scrubbed_request = request.dup
+        scrubbed_request[:body] = scrub_secrets(request[:body]) if request[:body].is_a?(String)
+        scrubbed_request[:headers] = scrub_headers(request[:headers]) if request[:headers].is_a?(Hash)
+        scrubbed_request
+      end
+
+      # dup (not a rebuilt Hash) so a Faraday::Utils::Headers keeps its
+      # class and case-insensitive lookup on the scrubbed copy.
+      def scrub_headers(headers)
+        scrubbed = headers.dup
+        scrubbed.each_key do |key|
+          scrubbed[key] = '[REDACTED]' if key.to_s.casecmp('authorization').zero?
+        end
+        scrubbed
       end
     end
   end

data/lib/platform_sdk/identity/zitadel/auth_client.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Identity
+    module Zitadel
+      # Fetches machine-user access tokens from Zitadel via client_credentials.
+      # Tokens are opaque bearer tokens; expiry tracking uses expires_in.
+      class AuthClient
+        include ErrorHandleable
+
+        API_SCOPE = 'openid urn:zitadel:iam:org:project:id:zitadel:aud'
+        EXPIRY_SKEW_SECONDS = 60
+        OPEN_TIMEOUT_SECONDS = 2
+        READ_TIMEOUT_SECONDS = 5
+
+        attr_reader :conn, :expires_at
+
+        def initialize(base_url, client_id, client_secret, scope: API_SCOPE)
+          @client_id = client_id
+          @client_secret = client_secret
+          @scope = scope
+          @token_lock = Mutex.new
+          @conn = build_connection(base_url)
+        end
+
+        # The lock makes concurrent callers (Puma/Sidekiq threads) share one
+        # fetch instead of racing: an unguarded reader could also observe
+        # @token assigned but @expires_at still nil mid-fetch and crash in
+        # expired?. Serializing on the bounded (2s/5s) fetch is acceptable
+        # for the shadow path.
+        def auth_token
+          @token_lock.synchronize do
+            fetch_token if expired?
+            @token
+          end
+        end
+
+        private
+
+        def build_connection(base_url)
+          Faraday.new(base_url) do |conn|
+            conn.request :url_encoded
+            conn.response :raise_error
+            conn.response :json
+            conn.options.open_timeout = OPEN_TIMEOUT_SECONDS
+            conn.options.timeout = READ_TIMEOUT_SECONDS
+            conn.adapter :net_http
+          end
+        end
+
+        def expired?
+          @token.nil? || Time.now.utc >= @expires_at
+        end
+
+        # Both fields are read into locals before either ivar is assigned: a
+        # malformed 200 (access_token without expires_in) must leave the cache
+        # untouched so the next call retries instead of comparing against a
+        # nil @expires_at forever.
+        def fetch_token
+          body = with_rescue { @conn.post('/oauth/v2/token', token_request_params).body }
+          token = body.fetch('access_token')
+          expires_at = Time.now.utc + body.fetch('expires_in').to_i - EXPIRY_SKEW_SECONDS
+          @token = token
+          @expires_at = expires_at
+        end
+
+        def token_request_params
+          {
+            grant_type: 'client_credentials',
+            client_id: @client_id,
+            client_secret: @client_secret,
+            scope: @scope
+          }
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/identity/zitadel/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Identity
+    module Zitadel
+      # Client for the Zitadel v2 user API. Deliberately mirrors the IS4
+      # Client's #provision_identity signature so consuming apps can call
+      # either interchangeably. Short timeouts, no retry middleware: this is
+      # the best-effort shadow path and must never hang a provisioning request.
+      #
+      # Token acquisition is a seam: the SDK ships Zitadel::AuthClient as the
+      # client_credentials implementation, but this class only needs an
+      # object responding to #auth_token. Consumers may pass an AuthClient
+      # directly, wrap one (e.g. a Rails.cache-backed provider that shares a
+      # token across processes), or supply any other object with that
+      # interface.
+      class Client
+        include ErrorHandleable
+
+        OPEN_TIMEOUT_SECONDS = 2
+        READ_TIMEOUT_SECONDS = 5
+
+        def initialize(base_url, token_provider)
+          @auth = token_provider
+          @conn = Faraday.new(base_url) do |conn|
+            conn.request :authorization, 'Bearer', -> { @auth.auth_token }
+            conn.request :json
+            conn.response :raise_error
+            conn.response :json
+            conn.options.open_timeout = OPEN_TIMEOUT_SECONDS
+            conn.options.timeout = READ_TIMEOUT_SECONDS
+            conn.adapter :net_http
+          end
+        end
+
+        def provision_identity(is4_params)
+          payload = UserPayload.from_is4(is4_params)
+          post_payload('/v2/users/human', payload)
+        rescue PlatformSdk::Identity::ClientError => e
+          raise unless e.response&.dig(:status) == 409
+
+          verify_existing!(payload, e)
+        end
+
+        private
+
+        # A 409 is idempotent-replay success only when the preserved id exists
+        # AND still holds this username; a matching id with a different
+        # username is a diverged record, not a replay, so the 409 stands.
+        def verify_existing!(payload, original_error)
+          user = fetch_user(payload[:userId], original_error)
+          raise original_error unless user['username'] == payload[:username]
+
+          { 'userId' => payload[:userId], 'alreadyExisted' => true }
+        end
+
+        # An inconclusive verify re-raises the conflict, not the transient: the
+        # 409 is the actionable signal (id or username collision) for the
+        # caller's hook. Faraday::Error is the ancestor of the SDK taxonomy
+        # (ClientError/ServerError/TimeoutError) AND of the transport failures
+        # with_rescue never maps (ConnectionFailed, SSLError, ParsingError), so
+        # a connect refusal or open timeout is inconclusive too, not a leak.
+        def fetch_user(user_id, original_error)
+          get_payload("/v2/users/#{user_id}").fetch('user', {})
+        rescue Faraday::Error
+          raise original_error
+        end
+
+        def get_payload(path)
+          with_rescue do
+            @conn.get(path).body
+          end
+        end
+
+        def post_payload(path, body)
+          with_rescue do
+            @conn.post(path) { |req| req.body = body }.body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/identity/zitadel/user_payload.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Identity
+    module Zitadel
+      # Maps the IS4 WithProfile payload shape onto Zitadel v2 AddHumanUser.
+      # sendPasswordResetEmail / PasswordResetReturnUrl are IS4-only concepts
+      # and are dropped. No password is ever sent: SIS creations are shells.
+      # The mixed key casing is faithful to the IS4 payload: PascalCase
+      # throughout except phoneNumber (see Services::Identity in Central).
+      module UserPayload
+        module_function
+
+        def from_is4(is4_params)
+          params = is4_params.transform_keys(&:to_s)
+          identity_fields(params)
+            .merge(profile: profile_fields(params))
+            .merge(optional_fields(params))
+        end
+
+        def identity_fields(params)
+          {
+            userId: required(params, 'Id'),
+            username: required(params, 'Username'),
+            email: { email: required(params, 'Email'), isVerified: false }
+          }
+        end
+
+        def profile_fields(params)
+          username = required(params, 'Username')
+          {
+            givenName: presence(params['FirstName']) || username,
+            familyName: presence(params['LastName']) || username
+          }
+        end
+
+        def optional_fields(params)
+          fields = {}
+          phone = presence(params['phoneNumber'])
+          fields[:phone] = { phone:, isVerified: false } if phone
+          fields.merge(metadata_fields(params))
+        end
+
+        def metadata_fields(params)
+          source_system_id = presence(params['SourceSystemId'])
+          return {} unless source_system_id
+
+          { metadata: [{ key: 'sourceSystemId', value: Base64.strict_encode64(source_system_id) }] }
+        end
+
+        # userId == IS4 Id is the migration's id-preservation invariant; a
+        # blank required field must raise here rather than reach Zitadel,
+        # which would mint its own id for a null userId.
+        def required(params, key)
+          presence(params[key]) || raise(ArgumentError, "IS4 payload is missing #{key}")
+        end
+
+        def presence(value)
+          stripped = value.to_s.strip
+          stripped.empty? ? nil : stripped
+        end
+        private_class_method :presence, :required, :metadata_fields, :optional_fields,
+                             :profile_fields, :identity_fields
+      end
+    end
+  end
+end

data/lib/platform_sdk/identity.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
-require "date"
-require "faraday"
-require "faraday/net_http"
-require "json"
-require "jwt"
+require 'base64'
+require 'date'
+require 'faraday'
+require 'faraday/net_http'
+require 'json'
+require 'jwt'
 
-require "platform_sdk/identity/error_handleable"
-require "platform_sdk/identity/clients"
+require 'platform_sdk/identity/error_handleable'
+require 'platform_sdk/identity/clients'
+require 'platform_sdk/identity/zitadel/auth_client'
+require 'platform_sdk/identity/zitadel/user_payload'
+require 'platform_sdk/identity/zitadel/client'
 
 module PlatformSdk
   module Identity

data/lib/platform_sdk/version.rb

@@ -2,8 +2,8 @@
 
 module PlatformSdk
   MAJOR = 3
-  MINOR = 32
+  MINOR = 33
   PATCH = 0
 
-  VERSION = "#{PlatformSdk::MAJOR}.#{PlatformSdk::MINOR}.#{PlatformSdk::PATCH}"
+  VERSION = "#{PlatformSdk::MAJOR}.#{PlatformSdk::MINOR}.#{PlatformSdk::PATCH}".freeze
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: strongmind-platform-sdk
 version: !ruby/object:Gem::Version
-  version: 3.32.0
+  version: 3.33.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-07-28 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -305,6 +319,9 @@ files:
 - lib/platform_sdk/identity.rb
 - lib/platform_sdk/identity/clients.rb
 - lib/platform_sdk/identity/error_handleable.rb
+- lib/platform_sdk/identity/zitadel/auth_client.rb
+- lib/platform_sdk/identity/zitadel/client.rb
+- lib/platform_sdk/identity/zitadel/user_payload.rb
 - lib/platform_sdk/jira.rb
 - lib/platform_sdk/jira/service_management_client.rb
 - lib/platform_sdk/jobs/send_noun_to_pipeline_job.rb