iorwerth-hub 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8fe7207839b271a72800dc05b9e9f8ed43b39208e765082e3272f548abc3035a
+  data.tar.gz: 050fad5950fea4cec1f3d54fa4d2a5fa8a366331a9933ec514d42191bb3fec81
+SHA512:
+  metadata.gz: 0c66317ece2c5fb5413f8ea43d1627e29a2af29d0b9aa39f6f366a7a54e5f84704ec4f517561625eed63c166074a1dea9c666a6618b4596e188a85ec2b26cef8
+  data.tar.gz: 987ca13d118419db3f8d9a9b11a35b87c96772388d5afd248f4e15526db858f634016781ec4b55fb4dd5d7ac4e01f5b7910e128d1f4f5798db9013570b6dc778

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First release: `Iorwerth::Hub::Client` for every `/api/v1` operation, `entitled?` and
+  `limit` with a cache that survives a Hub outage, `Webhook.verify` and a Rack
+  `Webhook::Receiver`, and the `:iorwerth_hub` OmniAuth strategy.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iorwerth Technologies
+
+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,226 @@
+# iorwerth-hub
+
+Connects a Ruby product to the Iorwerth Customer Hub. It provides four pieces:
+
+- **Sign-in:** the `:iorwerth_hub` OmniAuth strategy. OpenID Connect, code flow with PKCE.
+- **API client:** `Iorwerth::Hub::Client`, one method per `/api/v1` operation.
+- **Entitlement checks:** `Iorwerth::Hub.entitled?`, cached, and still answering while the Hub is down.
+- **Webhooks:** `Iorwerth::Hub::Webhook::Receiver`, a Rack endpoint that verifies each signature.
+
+Start with [Connecting a product to the Hub](../../docs/integration/connecting-a-product.md),
+which goes through every step: registering the product, credentials, plans, tenants
+and webhooks. This README covers the Ruby side of each.
+
+The Hub's contract is described in
+[docs/architecture/customer-hub.md](../../docs/architecture/customer-hub.md), Product integration contract.
+The API itself is defined by [apps/hub/openapi.json](../../apps/hub/openapi.json). A test in
+this gem fails if the client and that file disagree.
+
+## Install
+
+```ruby
+# Gemfile
+gem "iorwerth-hub"
+gem "omniauth_openid_connect"   # only for sign-in
+```
+
+Ruby 3.1 or later. The gem itself has no other dependencies.
+
+## Configure
+
+Every product reads the same environment variables. The Hub's admin prints them as a block when it
+issues the product's credentials:
+
+```
+HUB_URL=https://id.iorwerth.com
+HUB_PRODUCT_KEY=podium
+HUB_OIDC_CLIENT_ID=...
+HUB_OIDC_CLIENT_SECRET=...
+HUB_API_KEY=...
+HUB_WEBHOOK_SECRET=...
+```
+
+You can override any of them in code:
+
+```ruby
+Iorwerth::Hub.configure do |hub|
+  hub.cache = Rails.cache          # default: an in-process cache
+  hub.entitlements_ttl = 600       # seconds; default 300
+end
+```
+
+## Sign-in
+
+```ruby
+# config/initializers/omniauth.rb
+require "iorwerth/hub/omniauth"
+
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :iorwerth_hub, redirect_uri: "https://podium.app/auth/iorwerth_hub/callback"
+end
+```
+
+- **Signing in:** send people to `/auth/iorwerth_hub`. The callback receives the usual OmniAuth hash.
+- **Starting a trial:** send people to `/auth/iorwerth_hub?prompt=create&plan=<plan key>`. The Hub
+  shows its signup page and records the requested plan.
+
+The callback's `uid` is the Hub's `usr_` id. `info` holds the person's name and email.
+`Iorwerth::Hub.organizations(auth)` returns the organizations they belong to, as this
+product sees each one:
+
+```ruby
+def callback
+  auth = request.env["omniauth.auth"]
+  user = User.find_or_initialize_by(hub_id: auth.uid)
+  user.update!(email: auth.info.email, name: auth.info.name)
+  Iorwerth::Hub.organizations(auth).each do |organization|
+    tenant = Tenant.find_or_create_by!(hub_organization_id: organization["id"])
+    # ...
+  end
+end
+```
+
+## API
+
+```ruby
+hub = Iorwerth::Hub.client
+hub.get_organization("org_01J...")              # profile, members, subscription, entitlements
+hub.report_tenant("org_01J...", external_tenant_id: tenant.id.to_s)
+hub.report_usage("org_01J...", usage: { teams: 7 })
+hub.invite("org_01J...", email: "sam@example.com", role: "member")
+hub.each_organization { |organization| ... }    # every organization this product can see
+hub.each_event(since: last_event_id) { |event| ... }   # catch up after downtime
+```
+
+- **Answers:** the parsed JSON, as a Hash with string keys.
+- **Errors:** an error answer raises the matching subclass of `Iorwerth::Hub::ApiError`:
+  `NotFound`, `Refused` (422), `RateLimited`, and so on. Each carries the Hub's
+  `code` and message.
+- **Unreachable Hub:** raises `Iorwerth::Hub::ConnectionError`.
+- **Retries:** every POST sends an `Idempotency-Key`. To retry safely, pass the same
+  `idempotency_key:` again.
+
+## Entitlements
+
+```ruby
+Iorwerth::Hub.entitled?(organization_id, :stats)   # a switch, or a limit above 0
+Iorwerth::Hub.limit(organization_id, :teams)       # max_teams, or nil when there is none
+```
+
+- **Caching:** each organization's map is cached for `entitlements_ttl` seconds (300 by default).
+- **Hub outage:** if the Hub can't be reached once the cache has expired, the last
+  known map answers for up to a day. Customers keep their access.
+- **Unseen organizations:** one this product can't see is entitled to nothing.
+
+## Webhooks
+
+```ruby
+# config/routes.rb
+mount Iorwerth::Hub::Webhook::Receiver.new { |event| HubEventJob.perform_later(event) },
+      at: "/hub/webhooks"
+```
+
+The receiver handles signatures and caching for you:
+
+- It verifies `X-Hub-Signature` over the raw body and refuses timestamps more than
+  five minutes off.
+- It drops the organization's cached entitlements for `organization.*`, `member.*` and
+  `subscription.*` events.
+- It answers 204 once your block returns.
+
+Your block has two jobs:
+
+- **Return quickly:** do the work in a background job. If your block raises, the
+  request fails, and the Hub retries for a day.
+- **Process each event `id` once:** the Hub can deliver the same event again.
+
+Each event looks like this:
+
+```ruby
+{
+  "id" => "evt_01J...",
+  "type" => "member.added",
+  "created_at" => "2026-10-02T18:47:20.022Z",
+  "organization_id" => "org_01J...",
+  "product" => "podium",
+  "data" => {
+    "organization" => { ... },   # as get_organization returns it
+    "member" => { ... }
+  }
+}
+```
+
+To verify a webhook yourself: `Iorwerth::Hub::Webhook.verify(raw_body, header)`.
+
+## Developing
+
+```bash
+cd packages/hub-sdk-ruby
+bundle install
+bundle exec rake test
+```
+
+## Releasing
+
+Releases are published to RubyGems by `.github/workflows/sdk-ruby-release.yml` when a tag
+`sdk-ruby-vX.Y.Z` is pushed. It uses trusted publishing: RubyGems accepts the push because
+GitHub vouches for the workflow, so no RubyGems API key is stored anywhere.
+
+### One-time setup, before the first release
+
+The gem doesn't exist on RubyGems until its first push, so it starts as a *pending*
+trusted publisher. The first successful release turns that into the gem's real trusted
+publisher, owned by the account that created it.
+
+1. **Prepare a RubyGems account.** Sign in at [rubygems.org](https://rubygems.org), or
+   create an account, ideally one tied to a company address. Then turn on multi-factor
+   authentication: avatar menu → **Edit settings** → **Multi-factor authentication**.
+   The gemspec sets `rubygems_mfa_required`, so every owner needs MFA.
+2. **Check the name is free.** Visit `https://rubygems.org/gems/iorwerth-hub`. It should
+   show "This gem could not be found".
+3. **Add the pending publisher.** Avatar menu → **Edit settings** → **Trusted
+   publishers**, or go straight to
+   `https://rubygems.org/profile/oidc/pending_trusted_publishers`. Choose **Create**,
+   then fill in exactly:
+
+   | Field | Value |
+   | --- | --- |
+   | RubyGem name | `iorwerth-hub` |
+   | Trusted publisher type | GitHub Actions |
+   | Repository owner | `Iorwerth-technologies` |
+   | Repository name | `platform` |
+   | Workflow filename | `sdk-ruby-release.yml` (the file name only, not the path) |
+   | Environment | leave empty |
+
+   Save it. A pending publisher can expire if it goes unused, so do this shortly before
+   you tag. If the release later fails with a trusted-publishing error, check whether it
+   is still listed, and add it again if not.
+
+### Each release
+
+1. Set the new version in `lib/iorwerth/hub/version.rb`, add an entry to `CHANGELOG.md`,
+   and merge to `main`.
+2. Tag the merge commit and push the tag:
+   ```bash
+   git switch main && git pull
+   git tag sdk-ruby-v0.1.0 && git push origin sdk-ruby-v0.1.0
+   ```
+3. Watch the **sdk-ruby-release** run in GitHub Actions. It does four things, in order:
+   - checks that the tag matches `version.rb`
+   - runs the tests
+   - exchanges GitHub's token for a short-lived RubyGems key
+   - builds and pushes the gem
+4. Check that `https://rubygems.org/gems/iorwerth-hub` shows the new version. After the
+   first release, the gem's page lists the trusted publisher under its settings, in
+   place of the pending one.
+
+A version can't be pushed twice. If a release fails after the push step, fix forward with
+a new version.
+
+To share ownership with another account:
+`gem owner iorwerth-hub --add someone@example.com`. Run it from a machine signed in to
+RubyGems as an existing owner, with MFA.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/iorwerth/hub/client.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module Iorwerth
+  module Hub
+    # The Hub's /api/v1, one method per operation in apps/hub/openapi.json. A test in this
+    # gem fails if the spec gains an operation OPERATIONS does not have, or they disagree.
+    #
+    #   hub = Iorwerth::Hub::Client.new
+    #   hub.get_organization("org_01J...")["entitlements"]   # => {"max_teams" => 12}
+    #
+    # Answers are the parsed JSON (string keys). An error answer raises the ApiError
+    # subclass for its status; an unreachable Hub raises ConnectionError.
+    class Client
+      # operationId => [HTTP method, path]. Path parameters are {named} as in the spec.
+      OPERATIONS = {
+        "list_organizations" => [:get, "/api/v1/organizations"],
+        "get_organization" => [:get, "/api/v1/organizations/{organization_id}"],
+        "get_entitlements" => [:get, "/api/v1/organizations/{organization_id}/entitlements"],
+        "report_tenant" => [:post, "/api/v1/organizations/{organization_id}/tenant"],
+        "get_usage" => [:get, "/api/v1/organizations/{organization_id}/usage"],
+        "report_usage" => [:post, "/api/v1/organizations/{organization_id}/usage"],
+        "invite" => [:post, "/api/v1/organizations/{organization_id}/invites"],
+        "get_user" => [:get, "/api/v1/users/{user_id}"],
+        "list_events" => [:get, "/api/v1/events"],
+        "list_plans" => [:get, "/api/v1/plans"]
+      }.freeze
+
+      def initialize(url: Hub.config.url, api_key: Hub.config.api_key,
+                     timeout: Hub.config.timeout, open_timeout: Hub.config.open_timeout)
+        raise ConfigurationError, "Set HUB_URL." if url.nil? || url.empty?
+
+        @base = URI(url.chomp("/"))
+        @api_key = api_key
+        @timeout = timeout
+        @open_timeout = open_timeout
+      end
+
+      # The organizations this product can see, oldest first: {"data" => [...], "next_cursor" => ...}.
+      def list_organizations(cursor: nil, limit: nil)
+        call("list_organizations", query: { cursor: cursor, limit: limit })
+      end
+
+      # Every organization this product can see, page by page.
+      def each_organization(limit: 100, &block)
+        return enum_for(:each_organization, limit: limit) unless block
+
+        cursor = nil
+        loop do
+          page = list_organizations(cursor: cursor, limit: limit)
+          page["data"].each(&block)
+          cursor = page["next_cursor"] or break
+        end
+      end
+
+      def get_organization(organization_id)
+        call("get_organization", organization_id: organization_id)
+      end
+
+      # Just the flat map and the subscription: what Entitlements caches.
+      def get_entitlements(organization_id)
+        call("get_entitlements", organization_id: organization_id)
+      end
+
+      # Record the tenant this product provisioned. Reporting the same one again is harmless.
+      def report_tenant(organization_id, external_tenant_id:, idempotency_key: SecureRandom.uuid)
+        call("report_tenant", organization_id: organization_id,
+                              body: { external_tenant_id: external_tenant_id },
+                              idempotency_key: idempotency_key)
+      end
+
+      def get_usage(organization_id)
+        call("get_usage", organization_id: organization_id)
+      end
+
+      # Current figures, e.g. report_usage(id, usage: {teams: 7}); over a limit is reported, not refused.
+      def report_usage(organization_id, usage:, idempotency_key: SecureRandom.uuid)
+        call("report_usage", organization_id: organization_id, body: { usage: usage },
+                             idempotency_key: idempotency_key)
+      end
+
+      # The Hub sends the email, in this product's theme. role: "admin" or "member".
+      def invite(organization_id, email:, role:, invited_by: nil, idempotency_key: SecureRandom.uuid)
+        body = { email: email, role: role, invited_by: invited_by }.compact
+        call("invite", organization_id: organization_id, body: body, idempotency_key: idempotency_key)
+      end
+
+      def get_user(user_id)
+        call("get_user", user_id: user_id)
+      end
+
+      # The webhooks this product was sent, oldest first, after the event id `since`.
+      def list_events(since: nil, limit: nil)
+        call("list_events", query: { since: since, limit: limit })
+      end
+
+      # Every event after `since`, page by page: catching up after downtime.
+      def each_event(since: nil, limit: 100, &block)
+        return enum_for(:each_event, since: since, limit: limit) unless block
+
+        loop do
+          page = list_events(since: since, limit: limit)
+          page["data"].each(&block)
+          since = page["next_cursor"] or break
+        end
+      end
+
+      # A product's public plans, for a pricing page. The one call that sends no API key.
+      def list_plans(workspace:, product: Hub.config.product_key)
+        call("list_plans", query: { workspace: workspace, product: product }, authenticated: false)
+      end
+
+      private
+
+      def call(operation, body: nil, query: {}, idempotency_key: nil, authenticated: true, **path)
+        verb, template = OPERATIONS.fetch(operation)
+        uri = @base.dup
+        uri.path = @base.path + template.gsub(/\{(\w+)\}/) do
+          URI.encode_www_form_component(path.fetch(Regexp.last_match(1).to_sym).to_s)
+        end
+        query = query.compact
+        uri.query = URI.encode_www_form(query) unless query.empty?
+        request = (verb == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "iorwerth-hub-ruby/#{VERSION}"
+        if authenticated
+          raise ConfigurationError, "Set HUB_API_KEY." if @api_key.nil? || @api_key.empty?
+
+          request["Authorization"] = "Bearer #{@api_key}"
+        end
+        request["Idempotency-Key"] = idempotency_key if idempotency_key
+        if body
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+        end
+        handle(send_request(uri, request))
+      end
+
+      def send_request(uri, request)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: @open_timeout, read_timeout: @timeout) do |http|
+          http.request(request)
+        end
+      rescue SocketError, SystemCallError, Timeout::Error, IOError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError, "#{uri.host}: #{e.class}: #{e.message}"
+      end
+
+      def handle(response)
+        status = response.code.to_i
+        parsed = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+        return parsed if status < 400
+
+        error = parsed.is_a?(Hash) ? parsed.fetch("error", {}) : {}
+        raise ApiError.for(status, error["code"], error["message"] || "HTTP #{status}")
+      rescue JSON::ParserError
+        raise ApiError.for(status, nil, "HTTP #{status}, not JSON") if status >= 400
+
+        raise ServerError.new(status, nil, "The Hub answered HTTP #{status} without JSON.")
+      end
+    end
+  end
+end

data/lib/iorwerth/hub/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Iorwerth
+  module Hub
+    # The environment contract every product shares (architecture doc, Product integration
+    # contract). The Hub's admin prints these as a block to paste when it issues credentials.
+    class Configuration
+      attr_accessor :url, :product_key, :oidc_client_id, :oidc_client_secret, :api_key,
+                    :webhook_secrets, :entitlements_ttl, :cache, :timeout, :open_timeout
+
+      def initialize(env = ENV)
+        @url = env["HUB_URL"]&.chomp("/")
+        @product_key = env["HUB_PRODUCT_KEY"]
+        @oidc_client_id = env["HUB_OIDC_CLIENT_ID"]
+        @oidc_client_secret = env["HUB_OIDC_CLIENT_SECRET"]
+        @api_key = env["HUB_API_KEY"]
+        # Comma-separated, so a receiver can hold both secrets through a rotation.
+        @webhook_secrets = env.fetch("HUB_WEBHOOK_SECRET", "").split(",").map(&:strip).reject(&:empty?)
+        # The architecture doc's 5-15 minutes; webhooks invalidate sooner.
+        @entitlements_ttl = 300
+        # Anything with read/write/delete like Rails.cache; nil keeps a cache in memory.
+        @cache = nil
+        @timeout = 10
+        @open_timeout = 5
+      end
+
+      def require!(*names)
+        missing = names.select { |name| public_send(name).nil? || public_send(name).empty? }
+        return if missing.empty?
+
+        variables = missing.map { |name| "HUB_#{name.to_s.upcase}" }.join(", ")
+        raise ConfigurationError, "Set #{variables} (Iorwerth::Hub.configure or the environment)."
+      end
+    end
+  end
+end

data/lib/iorwerth/hub/entitlements.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Iorwerth
+  module Hub
+    # Cached entitlement checks, per organization (architecture doc: products cache for a
+    # short TTL and treat webhooks as the invalidator).
+    #
+    #   Iorwerth::Hub.entitled?(organization_id, :stats)        # a switch, or a limit above 0
+    #   Iorwerth::Hub.limit(organization_id, :teams)            # max_teams, or nil for none
+    #
+    # If the Hub cannot be reached when an entry is stale, the last known map is used:
+    # a Hub outage means stale entitlements, never a locked-out organization.
+    class Entitlements
+      # Stale entries are kept this long, to answer from while the Hub is down.
+      KEEP_STALE = 24 * 60 * 60
+
+      def initialize(client: nil, ttl: Hub.config.entitlements_ttl, cache: Hub.config.cache)
+        @client = client
+        @ttl = ttl
+        @cache = cache || MemoryCache.new
+      end
+
+      # The flat map, e.g. {"max_teams" => 12, "stats" => true, "past_due" => false}.
+      def for(organization_id)
+        entry = @cache.read(key(organization_id))
+        return entry["entitlements"] if entry && Time.now.to_f - entry["fetched_at"] < @ttl
+
+        fetch(organization_id)
+      rescue ConnectionError, ServerError
+        raise unless entry
+
+        entry["entitlements"]
+      end
+
+      def entitled?(organization_id, name)
+        value = self.for(organization_id)[name.to_s]
+        value == true || (value.is_a?(Integer) && value.positive?)
+      rescue NotFound
+        false
+      end
+
+      # The limit `max_<name>` grants, or nil when the plan sets none.
+      def limit(organization_id, name)
+        value = self.for(organization_id)["max_#{name}"]
+        value.is_a?(Integer) ? value : nil
+      end
+
+      def invalidate(organization_id)
+        @cache.delete(key(organization_id))
+      end
+
+      private
+
+      def fetch(organization_id)
+        map = client.get_entitlements(organization_id).fetch("entitlements")
+        @cache.write(key(organization_id), { "entitlements" => map, "fetched_at" => Time.now.to_f },
+                     expires_in: KEEP_STALE)
+        map
+      end
+
+      def client
+        @client ||= Client.new
+      end
+
+      def key(organization_id)
+        "iorwerth-hub/entitlements/#{organization_id}"
+      end
+    end
+
+    # The read/write/delete subset of Rails.cache, in memory and thread-safe.
+    class MemoryCache
+      def initialize
+        @entries = {}
+        @lock = Mutex.new
+      end
+
+      def read(key)
+        @lock.synchronize do
+          value, expires_at = @entries[key]
+          next value if expires_at.nil? || Time.now.to_f < expires_at
+
+          @entries.delete(key)
+          nil
+        end
+      end
+
+      def write(key, value, expires_in: nil)
+        @lock.synchronize { @entries[key] = [value, expires_in && (Time.now.to_f + expires_in)] }
+        true
+      end
+
+      def delete(key)
+        @lock.synchronize { !@entries.delete(key).nil? }
+      end
+    end
+  end
+end

data/lib/iorwerth/hub/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Iorwerth
+  module Hub
+    class Error < StandardError; end
+
+    class ConfigurationError < Error; end
+
+    # The Hub could not be reached, or did not answer in time.
+    class ConnectionError < Error; end
+
+    # An answer in the Hub's error envelope: {"error": {"code": ..., "message": ...}}.
+    class ApiError < Error
+      attr_reader :status, :code
+
+      def initialize(status, code, message)
+        @status = status
+        @code = code
+        super(message)
+      end
+
+      def self.for(status, code, message)
+        klass = case status
+                when 400 then InvalidRequest
+                when 401 then Unauthorized
+                when 403 then Forbidden
+                when 404 then NotFound
+                when 422 then Refused
+                when 429 then RateLimited
+                when 500..599 then ServerError
+                else ApiError
+                end
+        klass.new(status, code, message)
+      end
+    end
+
+    class InvalidRequest < ApiError; end
+    class Unauthorized < ApiError; end
+    class Forbidden < ApiError; end
+    # Also what an organization this product cannot see looks like.
+    class NotFound < ApiError; end
+    # The Hub's rules refused it (422), e.g. a different tenant for a linked organization.
+    class Refused < ApiError; end
+    class RateLimited < ApiError; end
+    class ServerError < ApiError; end
+
+    # A webhook whose signature or timestamp did not check out.
+    class SignatureError < Error; end
+  end
+end

data/lib/iorwerth/hub/omniauth.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "iorwerth/hub"
+require "omniauth_openid_connect"
+
+module OmniAuth
+  module Strategies
+    # Sign-in through the Hub: OpenID Connect, authorization code with S256 PKCE, the
+    # endpoints discovered from HUB_URL. Needs omniauth_openid_connect in the app's Gemfile.
+    #
+    #   # config/initializers/omniauth.rb
+    #   require "iorwerth/hub/omniauth"
+    #   Rails.application.config.middleware.use OmniAuth::Builder do
+    #     provider :iorwerth_hub, redirect_uri: "https://podium.app/auth/iorwerth_hub/callback"
+    #   end
+    #
+    # Link to /auth/iorwerth_hub to sign in, or /auth/iorwerth_hub?prompt=create&plan=<key>
+    # for "Start free trial": the Hub shows signup and records the plan. The auth hash's
+    # extra.raw_info carries the `organizations` claim (Iorwerth::Hub.organizations(auth)).
+    class IorwerthHub < OpenIDConnect
+      option :name, "iorwerth_hub"
+      option :discovery, true
+      option :pkce, true
+      option :response_type, "code"
+      option :scope, %i[openid email profile]
+      option :allow_authorize_params, %i[plan]
+
+      def initialize(app, *args, &block)
+        super
+        config = Iorwerth::Hub.config
+        config.require!(:url, :oidc_client_id, :oidc_client_secret)
+        hub = URI(config.url)
+        options.issuer ||= config.url
+        options.client_options.identifier ||= config.oidc_client_id
+        options.client_options.secret ||= config.oidc_client_secret
+        options.client_options.scheme = hub.scheme
+        options.client_options.host = hub.host
+        options.client_options.port = hub.port
+      end
+
+      def request_phase
+        # OpenID Connect Prompt Create: a new customer lands on the Hub's signup.
+        options.prompt = "create" if request.params["prompt"] == "create"
+        super
+      end
+    end
+  end
+end

data/lib/iorwerth/hub/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Iorwerth
+  module Hub
+    VERSION = "0.1.0"
+  end
+end

data/lib/iorwerth/hub/webhook.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Iorwerth
+  module Hub
+    # The Hub's signed webhooks (architecture doc, Auth design):
+    #
+    #   X-Hub-Signature: t=1759420800,v1=5257a8...[,v1=...]
+    #
+    # each v1 an HMAC-SHA256 hex of "<t>.<raw body>" under one of the product's live
+    # secrets (several during a rotation). Verify over the raw body, before parsing it.
+    module Webhook
+      HEADER = "HTTP_X_HUB_SIGNATURE"
+      # Older than this is refused, as is a timestamp this far in the future.
+      TOLERANCE = 5 * 60
+
+      # The parsed event, or SignatureError.
+      def self.verify(payload, header, secrets: Hub.config.webhook_secrets, now: Time.now.to_i,
+                      tolerance: TOLERANCE)
+        raise SignatureError, "No webhook secret: set HUB_WEBHOOK_SECRET." if secrets.empty?
+
+        timestamp, signatures = parse(header)
+        raise SignatureError, "The timestamp is too old or too new." if (now - timestamp).abs > tolerance
+
+        signed = "#{timestamp}.#{payload}"
+        expected = secrets.map { |secret| OpenSSL::HMAC.hexdigest("SHA256", secret, signed) }
+        valid = expected.any? do |digest|
+          signatures.any? do |given|
+            given.bytesize == digest.bytesize && OpenSSL.fixed_length_secure_compare(given, digest)
+          end
+        end
+        raise SignatureError, "The signature does not match." unless valid
+
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        raise SignatureError, "The body is not JSON."
+      end
+
+      def self.parse(header)
+        parts = header.to_s.split(",").map { |part| part.strip.split("=", 2) }
+        timestamp = parts.find { |name, _| name == "t" }&.last
+        signatures = parts.select { |name, _| name == "v1" }.map(&:last)
+        raise SignatureError, "No X-Hub-Signature, or not t=...,v1=..." if timestamp !~ /\A\d+\z/ || signatures.empty?
+
+        [timestamp.to_i, signatures]
+      end
+      private_class_method :parse
+
+      # A Rack endpoint for POST /hub/webhooks. Mount it, then handle each verified event:
+      #
+      #   # config/routes.rb
+      #   mount(Iorwerth::Hub::Webhook::Receiver.new { |event| HubEventJob.perform_later(event) },
+      #         at: "/hub/webhooks")
+      #
+      # Answers 204 once the handler returns, so do the work in a job and return quickly; an
+      # error in the handler answers 500 and the Hub retries. Event ids repeat on a retry:
+      # process each once. Organization, member and subscription events drop the
+      # organization's cached entitlements before the handler runs.
+      class Receiver
+        INVALIDATES = /\A(organization|member|subscription)\./
+
+        def initialize(secrets: nil, entitlements: nil, &handler)
+          raise ArgumentError, "Pass a block to handle each event." unless handler
+
+          @secrets = secrets
+          @entitlements = entitlements
+          @handler = handler
+        end
+
+        def call(env)
+          return respond(405, "POST only") unless env["REQUEST_METHOD"] == "POST"
+
+          body = env["rack.input"].read
+          env["rack.input"].rewind if env["rack.input"].respond_to?(:rewind)
+          event = Webhook.verify(body, env[HEADER], secrets: @secrets || Hub.config.webhook_secrets)
+          if event["organization_id"] && event["type"].to_s.match?(INVALIDATES)
+            (@entitlements || Hub.entitlements).invalidate(event["organization_id"])
+          end
+          @handler.call(event)
+          [204, {}, []]
+        rescue SignatureError => e
+          respond(400, e.message)
+        end
+
+        private
+
+        def respond(status, message)
+          [status, { "content-type" => "text/plain" }, [message]]
+        end
+      end
+    end
+  end
+end

data/lib/iorwerth/hub.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "iorwerth/hub/version"
+require "iorwerth/hub/errors"
+require "iorwerth/hub/configuration"
+require "iorwerth/hub/client"
+require "iorwerth/hub/entitlements"
+require "iorwerth/hub/webhook"
+
+module Iorwerth
+  # Connects a Ruby product to the Iorwerth Customer Hub. Reads its settings from the
+  # HUB_* environment variables; `configure` overrides them.
+  #
+  # Sign-in lives in iorwerth/hub/omniauth, required separately: it needs
+  # omniauth_openid_connect, which the core does not.
+  module Hub
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        @client = @entitlements = nil
+        config
+      end
+
+      def client
+        @client ||= Client.new
+      end
+
+      def entitlements
+        @entitlements ||= Entitlements.new
+      end
+
+      def entitled?(organization_id, name)
+        entitlements.entitled?(organization_id, name)
+      end
+
+      def limit(organization_id, name)
+        entitlements.limit(organization_id, name)
+      end
+
+      # The `organizations` claim from an OmniAuth auth hash: [{"id" =>, "name" =>, "role" =>, ...}].
+      def organizations(auth)
+        info = auth.dig("extra", "raw_info") || {}
+        info = info.to_h if info.respond_to?(:to_h)
+        info.fetch("organizations", info.fetch(:organizations, []))
+      end
+
+      # Forget settings and cached state; for tests.
+      def reset!
+        @config = @client = @entitlements = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: iorwerth-hub
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Iorwerth Technologies
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-02 00:00:00.000000000 Z
+dependencies: []
+description: Sign-in through the Hub (OmniAuth), its /api/v1 client, cached entitlement
+  checks, and a Rack endpoint that verifies the Hub's webhooks.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/iorwerth/hub.rb
+- lib/iorwerth/hub/client.rb
+- lib/iorwerth/hub/configuration.rb
+- lib/iorwerth/hub/entitlements.rb
+- lib/iorwerth/hub/errors.rb
+- lib/iorwerth/hub/omniauth.rb
+- lib/iorwerth/hub/version.rb
+- lib/iorwerth/hub/webhook.rb
+homepage: https://github.com/Iorwerth-technologies/platform/tree/main/packages/hub-sdk-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Iorwerth-technologies/platform/tree/main/packages/hub-sdk-ruby
+  changelog_uri: https://github.com/Iorwerth-technologies/platform/tree/main/packages/hub-sdk-ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Connect a Ruby product to the Iorwerth Customer Hub
+test_files: []