katalyst-google-apis 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a4c525102b4817651ef073cf9da2c39a679a331c900eaf84bcde18d92a3141b
+  data.tar.gz: 62c1ced1409c7bb4a14531834a373c2f0b495b41be66cbc6859cadfbb1d9c9f4
+SHA512:
+  metadata.gz: 69060627b5f85a9ea12f7a74a4dd1b847d8ce88fe2b26d9e3c15025ae6e4b85af1a1e1a4f44288270493735674480a0cab3a851f00124326b52a59433c3909bb
+  data.tar.gz: 1e8c146a0e5e9c2146aeb5a034f3fea27f75116734b3d7c8ddfcadcac9d16efd5ddff0dc31c811d728528c00c0886038ec8aa6a3890af221e662cf72134da556

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Katalyst Interactive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Katalyst::GoogleApis
+
+Katalyst Google APIs provides a simple interface for integrating Google REST
+APIs into Rails projects, with built-in support for AWS ECS OIDC authentication
+and Recaptcha validation.
+
+This project is an alternative approach to using the gRPC libraries provided by
+Google, which require specific fork behaviour that (as of 2025) are
+[not compatible with puma](https://github.com/puma/puma/issues/3503).
+
+## Installation
+
+Install the gem as usual
+
+```ruby
+gem "katalyst-google-apis"
+```
+
+## Usage
+
+Configure your google service account and project in an initializer:
+
+```ruby
+Katalyst::GoogleApis.configure do |config|
+  config.project_id            = "prj-..."
+  config.project_number        = "..."
+  config.service_account_email = ENV.fetch("GOOGLE_SERVICE_ACCOUNT_EMAIL", "sa-...@....iam.gserviceaccount.com")
+  config.identity_pool         = "...-pool"
+  config.identity_provider     = "...-provider"
+
+  # Recaptcha configuration
+  # site_keys appear in the frontend, they white-list domains so do not need to be kept secret
+  config.recaptcha.site_key = ENV.fetch("RECAPTCHA_SITE_KEY", "...")
+end
+```
+
+These can also be configured using ENV variables, see Katalyst::GoogleApis::Config for details.
+
+### Enterprise Recaptcha
+
+Add a token field and validation to your model:
+
+```ruby
+attr_accessor :recaptcha_token
+validates :recaptcha_token, recaptcha: true, on: :create
+```
+
+Add to permitted params in your controller, and add the field to your views:
+
+```erb
+<%= form.govuk_recaptcha_field :recaptcha_token %>
+```
+
+Test by adding `require "katalyst/google_apis/matchers"` to your `spec/rails_helpers.rb`.
+
+You can test any or all of the following in your model:
+
+```ruby
+  it { is_expected.to validate_recaptcha_for(:recaptcha_token, expected: :recaptcha_blank).on(:create) }
+  it { is_expected.to validate_recaptcha_for(:recaptcha_token, expected: :recaptcha_invalid).on(:create) }
+  it { is_expected.to validate_recaptcha_for(:recaptcha_token, expected: :recaptcha_action_mismatch).on(:create) }
+  it { is_expected.to validate_recaptcha_for(:recaptcha_token, expected: :recaptcha_suspicious).on(:create) }
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. We do not
+currently have a dummy app and specs, so test against an existing project.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/google-apis.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/javascripts/controllers/recaptcha_controller.js

@@ -0,0 +1,46 @@
+import { Controller } from "@hotwired/stimulus";
+
+const config = (window["___grecaptcha_cfg"] ||= {});
+config["fns"] ||= [];
+
+const recaptcha = (window["grecaptcha"] ||= {});
+const enterprise = (recaptcha["enterprise"] ||= {});
+
+enterprise.ready = (f) => {
+  (config["fns"] ||= []).push(f);
+};
+
+function init() {
+  if (document.head.querySelector("script[src*='recaptcha/enterprise']"))
+    return;
+
+  const script = document.createElement("script");
+  script.setAttribute(
+    "src",
+    "https://www.google.com/recaptcha/enterprise.js?render=explicit",
+  );
+  script.toggleAttribute("async", true);
+  script.toggleAttribute("defer", true);
+
+  document.head.appendChild(script);
+}
+
+export default class RecaptchaController extends Controller {
+  connect() {
+    init();
+
+    enterprise.ready(() => {
+      enterprise.render(this.element, {
+        sitekey: this.element.dataset.sitekey,
+        action: this.element.dataset.action,
+        callback: (response) => {
+          this.responseTarget.value = response;
+        },
+      });
+    });
+  }
+
+  get responseTarget() {
+    return this.element.nextElementSibling;
+  }
+}

data/app/helpers/katalyst/google_apis/form_builder.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    module FormBuilder
+      def recaptcha_field(attribute = :recaptcha_token, action: object_name,
+sitekey: GoogleApis.config.recaptcha.site_key)
+        safe_join([
+                    content_tag(:div, "", data: { action:, controller: "recaptcha", sitekey: }),
+                    hidden_field(attribute),
+                  ])
+      end
+    end
+  end
+end

data/app/helpers/katalyst/google_apis/govuk_form_builder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    module GOVUKFormBuilder
+      def govuk_recaptcha_field(attribute = :recaptcha_token, **)
+        GOVUKDesignSystemFormBuilder::Containers::FormGroup.new(self, object_name, attribute).html do
+          safe_join([
+                      GOVUKDesignSystemFormBuilder::Elements::ErrorMessage.new(self, object_name, attribute),
+                      recaptcha_field(attribute, **),
+                    ])
+        end
+      end
+    end
+  end
+end

data/app/services/katalyst/google_apis/credentials.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "aws-sdk-core"
+
+module Katalyst
+  module GoogleApis
+    class Credentials < Google::Auth::ExternalAccount::AwsCredentials
+      def initialize(**)
+        super(Config.new(**).to_h)
+
+        @aws_provider = ::Aws::CredentialProviderChain.new.resolve
+      end
+
+      # Override the default implementation that only supports EC2 credentials.
+      def fetch_security_credentials
+        # Note: Aws::CredentialProviderChain is a private API, but because it is
+        # consumed directly by AWS utilities we assume it's stable.
+        # This approach would not be required if Google's base class supported
+        # resolving credentials from ECS environments.
+        credentials = @aws_provider.credentials
+
+        # Short-lived credentials for the AWS ECS instance role
+        # These are used to authenticate the call to Google Cloud to authenticate
+        # to the GC service account using OIDC based on the AWS ECS identity.
+        {
+          access_key_id:     credentials.access_key_id,
+          secret_access_key: credentials.secret_access_key,
+          session_token:     credentials.session_token,
+        }
+      end
+
+      def region
+        @region ||= @aws_provider.client.config.region
+      end
+
+      class Config
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+
+        attribute :scope, :string, default: "https://www.googleapis.com/auth/cloud-platform"
+        attribute :service_account_email, :string
+        attribute :project_number, :integer
+        attribute :identity_pool, :string
+        attribute :identity_provider, :string
+        attribute :token_lifetime_seconds, :integer, default: 3600
+
+        def audience
+          ["//iam.googleapis.com", *{
+            projects:              project_number,
+            locations:             "global",
+            workloadIdentityPools: identity_pool,
+            providers:             identity_provider,
+          }].join("/")
+        end
+
+        def service_account_impersonation_url
+          ["https://iamcredentials.googleapis.com/v1", *{
+            projects:        "-",
+            serviceAccounts: "#{service_account_email}:generateAccessToken",
+          }].join("/")
+        end
+
+        def regional_cred_verification_url
+          "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
+        end
+
+        def subject_token_type
+          "urn:ietf:params:aws:token-type:aws4_request"
+        end
+
+        def token_url
+          "https://sts.googleapis.com/v1/token"
+        end
+
+        def universe_domain
+          "googleapis.com"
+        end
+
+        def type
+          "external_account"
+        end
+
+        def to_h
+          {
+            scope:,
+            universe_domain:,
+            type:,
+            audience:,
+            subject_token_type:,
+            token_url:,
+            service_account_impersonation_url:,
+            service_account_impersonation:     { token_lifetime_seconds: },
+            credential_source:                 { regional_cred_verification_url: },
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/katalyst/google_apis/recaptcha/assessment_service.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    module Recaptcha
+      class AssessmentService
+        attr_accessor :response, :result, :error
+
+        def self.call(parent:, credentials: GoogleApis.credentials, **)
+          new(credentials:, parent:).call(**)
+        end
+
+        def initialize(credentials:, parent:)
+          @credentials = credentials
+          @parent      = parent
+        end
+
+        def call(assessment:)
+          @response = Curl.post(url, assessment.to_json) do |http|
+            http.headers["Content-Type"] = "application/json; UTF-8"
+            @credentials.apply!(http.headers)
+          end
+
+          @result = JSON.parse(@response.body, symbolize_names: true)
+
+          self
+        rescue Curl::Easy::Error => e
+          if defined?(Sentry)
+            Sentry.add_breadcrumb(sentry_breadcrumb(e))
+          else
+            Rails.logger.error(e)
+          end
+
+          @error = e
+          self
+        end
+
+        def valid?
+          @result.present? && @result.dig(:tokenProperties, :valid)
+        end
+
+        def action
+          return nil unless valid?
+
+          @result.dig(:tokenProperties, :action)
+        end
+
+        def score
+          return nil unless valid?
+
+          @result.dig(:riskAnalysis, :score)
+        end
+
+        def inspect
+          "#<#{self.class.name} result: #{@result.inspect} error: #{@error.inspect}>"
+        end
+
+        private
+
+        def url
+          "https://recaptchaenterprise.googleapis.com/v1/#{@parent}/assessments"
+        end
+
+        def sentry_breadcrumb(error)
+          Sentry::Breadcrumb.new(
+            type:        "http",
+            category:    "recaptcha",
+            url:,
+            method:      "POST",
+            status_code: error.code,
+            reason:      error.message,
+          )
+        end
+      end
+    end
+  end
+end

data/app/validators/recaptcha_validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Example:
+#     validates :recaptcha_token, recaptcha: { score: 0.5 }, on: :create
+class RecaptchaValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, token)
+    return if Katalyst::GoogleApis.config.recaptcha.test_mode
+
+    action     = options.fetch(:action, record.class.model_name.param_key)
+    project_id = options.fetch(:project_id, Katalyst::GoogleApis.config.project_id)
+    score      = options.fetch(:score, Katalyst::GoogleApis.config.recaptcha.score)
+    site_key   = options.fetch(:site_key, Katalyst::GoogleApis.config.recaptcha.site_key)
+
+    if token.blank?
+      record.errors.add(attribute, :recaptcha_blank)
+      return
+    end
+
+    response = Katalyst::GoogleApis::Recaptcha::AssessmentService.call(
+      parent:     "projects/#{project_id}",
+      assessment: { event: { site_key:, token: } },
+    )
+
+    if !response.valid?
+      record.errors.add(attribute, :recaptcha_invalid)
+    elsif response.action != action
+      record.errors.add(attribute, :recaptcha_action_mismatch)
+    elsif response.score < score
+      record.errors.add(attribute, :recaptcha_suspicious)
+    end
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+pin_all_from Katalyst::GoogleApis::Engine.root.join("app/assets/javascripts/controllers"),
+             under: "controllers"

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  errors:
+    messages:
+      recaptcha_blank: "Please verify that you're not a robot."
+      recaptcha_invalid: "There was a problem verifying your submission. Please try again."
+      recaptcha_action_mismatch: "Something went wrong with the form validation. Please refresh the page and try again."
+      recaptcha_suspicious: "We couldn't verify your submission. Please try again or contact support if the problem persists."

data/lib/katalyst/google_apis/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    class Config
+      include ActiveSupport::Configurable
+
+      config_accessor(:project_id) { ENV.fetch("GOOGLE_PROJECT_ID", nil) }
+      config_accessor(:project_number) { ENV.fetch("GOOGLE_PROJECT_NUMBER", nil) }
+      config_accessor(:service_account_email) { ENV.fetch("GOOGLE_SERVICE_ACCOUNT_EMAIL", nil) }
+      config_accessor(:identity_pool) { ENV.fetch("GOOGLE_OIDC_IDENTITY_POOL", nil) }
+      config_accessor(:identity_provider) { ENV.fetch("GOOGLE_OIDC_IDENTITY_PROVIDER", nil) }
+
+      config_accessor(:recaptcha) do
+        defaults           = ActiveSupport::OrderedOptions.new
+        defaults.site_key  = ENV.fetch("GOOGLE_RECAPTCHA_SITE_KEY", nil)
+        defaults.score     = ENV.fetch("GOOGLE_RECAPTCHA_SCORE", 0.5).to_f
+        defaults.test_mode = !ENV.fetch("VERIFY_RECAPTCHA", !Rails.env.local?) # rubocop:disable Rails/UnknownEnv
+        defaults
+      end
+    end
+  end
+end

data/lib/katalyst/google_apis/engine.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Katalyst
+  module GoogleApis
+    class Engine < ::Rails::Engine
+      initializer "katalyst-google-apis.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << root.join("config/importmap.rb")
+          app.config.importmap.cache_sweepers << root.join("app/javascript/controllers")
+        end
+      end
+
+      initializer "katalyst-google-apis.forms" do |app|
+        app.config.after_initialize do
+          ActionView::Helpers::FormBuilder.include(Katalyst::GoogleApis::FormBuilder)
+          if defined?(GOVUKDesignSystemFormBuilder)
+            GOVUKDesignSystemFormBuilder::Builder.include(Katalyst::GoogleApis::GOVUKFormBuilder)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/katalyst/google_apis/matchers/validate_recaptcha_for_matcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    module Matchers
+      def validate_recaptcha_for(attribute, expected: :recaptcha_suspicious)
+        matcher = ValidateRecaptchaForMatcher.new(attribute, expected:)
+
+        if (response = matcher.example_response(subject))
+          service = instance_double(Recaptcha::AssessmentService)
+          allow(service).to receive_messages(**response)
+          allow(Recaptcha::AssessmentService).to receive(:call).and_return(service)
+        end
+
+        matcher
+      end
+
+      class ValidateRecaptchaForMatcher < Shoulda::Matchers::ActiveModel::ValidationMatcher
+        def initialize(attribute, expected:)
+          super(attribute)
+
+          @expected_message = expected
+        end
+
+        def matches?(subject)
+          Katalyst::GoogleApis.config.recaptcha.test_mode = false
+
+          super
+
+          disallows_value_of(example_value, @expected_message)
+        ensure
+          Katalyst::GoogleApis.config.recaptcha.test_mode = true
+        end
+
+        def simple_description
+          "validate that :#{@attribute} includes reCAPTCHA validation"
+        end
+
+        def example_value
+          {
+            recaptcha_invalid:         "<invalid-token>",
+            recaptcha_action_mismatch: "<action-mismatch-token>",
+            recaptcha_suspicious:      "<suspicious-token>",
+          }[@expected_message]
+        end
+
+        def example_response(subject)
+          case @expected_message
+          when :recaptcha_invalid
+            { valid?: false }
+          when :recaptcha_action_mismatch
+            { valid?: true, action: "mismatch" }
+          when :recaptcha_suspicious
+            { valid?: true, action: subject.class.model_name.param_key, score: 0.1 }
+          else
+            { valid?: true, action: subject.class.model_name.param_key, score: 0.9 }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/katalyst/google_apis/matchers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module GoogleApis
+    module Matchers
+    end
+  end
+end
+
+require_relative "matchers/validate_recaptcha_for_matcher"

data/lib/katalyst/google_apis.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "katalyst/google_apis/engine"
+
+module Katalyst
+  module GoogleApis
+    extend self
+    extend ActiveSupport::Autoload
+
+    autoload :Config
+
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    def credentials
+      @credentials ||= Credentials.new(
+        project_number:        config.project_number,
+        service_account_email: config.service_account_email,
+        identity_pool:         config.identity_pool,
+        identity_provider:     config.identity_provider,
+      )
+    end
+  end
+end

data/lib/katalyst-google-apis.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "katalyst/google_apis"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: katalyst-google-apis
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Katalyst Interactive
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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: googleauth
+  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'
+email:
+- developers@katalyst.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/assets/javascripts/controllers/recaptcha_controller.js
+- app/helpers/katalyst/google_apis/form_builder.rb
+- app/helpers/katalyst/google_apis/govuk_form_builder.rb
+- app/services/katalyst/google_apis/credentials.rb
+- app/services/katalyst/google_apis/recaptcha/assessment_service.rb
+- app/validators/recaptcha_validator.rb
+- config/importmap.rb
+- config/locales/en.yml
+- lib/katalyst-google-apis.rb
+- lib/katalyst/google_apis.rb
+- lib/katalyst/google_apis/config.rb
+- lib/katalyst/google_apis/engine.rb
+- lib/katalyst/google_apis/matchers.rb
+- lib/katalyst/google_apis/matchers/validate_recaptcha_for_matcher.rb
+homepage: https://github.com/katalyst/google-apis
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Google REST APIs for use in Rails projects
+test_files: []