iorwerth-hub 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe00c674601d7abf791b03dda0dfc53104eb0f555c125060ebaa2634e5e3ccb6
-  data.tar.gz: fee576c01b5f1a62b7057d696a19a5f8cb0f3411528bce182e817a8c8b61d462
+  metadata.gz: cb15506bb31b75a41adcff9d816410edfbb6386f73046d972ad2588b0974a500
+  data.tar.gz: ef02264de56eb7fa73b6210b4a2f017ab83b94ba114c58ba35355d84ce9e60d2
 SHA512:
-  metadata.gz: 288a3cef72db3fac3c58d97de710dcc5aa40088d661d80fab1999d7790c0104e3c0f8df7e28f22ce989ba60c22743ac5d7dbe4f40d0f6e9e6fda60691cd77d0c
-  data.tar.gz: 44121888f35a9809e5de9455a9a953fb9421836955dcb512a95c6db000cb1dd60583447ce7324fc0897a1aa994deb0e52bf9e5e63308831d4017c37ae0714596
+  metadata.gz: 65995baaa899db6097a4997a86acad674b3d3272166fa8055ac558c69738eb171a99edb99cace0fa93496b99b05a6af252ebe6f1c1d3c5b90f5e9a7c0be64d66
+  data.tar.gz: 72f260c64686c7c0e92edfc16d704b1060106f4c467a5dd771adccbc8c08f1677d17a14ad61d792869d37af1d8ce22dee00a25185390200b6d66ef804479e405

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.0
+
+- `Iorwerth::Hub.end_session`: RP-initiated logout. Builds the request to the Hub's
+  end-session endpoint (discovered, not hard-coded) so a product's "Log out" ends the
+  Hub session too; POST `endpoint` + `params` to keep the ID token out of URLs, and the
+  Hub returns the browser to `redirect_uri` with `state` unchanged.
+
+## 0.2.0
+
+- `checkout` and `portal`: Stripe Checkout and Customer Portal URLs for an organization.
+  `checkout` without `plan:` buys the plan the organization requested at signup.
+- `list_plans` answers no longer carry `ends_on`, and `interval` is `month` or `year`:
+  the Hub has no seasonal plans (ADR-0010).
+
 ## 0.1.1
 
 - Sign-in works against a Hub on plain http, such as the local one from

data/README.md

@@ -77,13 +77,50 @@ 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|
+  # Each has "type": "business" or "personal". A product whose customers are
+  # organizations provisions business ones; one for individuals, the personal one.
+  Iorwerth::Hub.organizations(auth).select { |o| o["type"] == "business" }.each do |organization|
     tenant = Tenant.find_or_create_by!(hub_organization_id: organization["id"])
     # ...
   end
 end
 ```
 
+## Signing out
+
+"Log out" must end the Hub session too, or the next sign-in is silent. Clear your own
+session first, then send the browser to the Hub's end-session endpoint. POST it so the ID
+token stays out of URLs; the Hub returns to `post_logout_redirect_uri` with `state`
+unchanged, which you can use to pick where to land.
+
+```ruby
+# config/initializers/omniauth.rb — register the return URL with the Hub, per product:
+#   post_logout_redirect_uris = https://podium.app/auth/hub/signed_out
+
+def destroy            # DELETE /logout
+  id_token = session[:hub_id_token]   # saved from auth.credentials.id_token at sign-in
+  reset_session                       # end the product's own session first
+  @logout = Iorwerth::Hub.end_session(
+    id_token: id_token,
+    redirect_uri: signed_out_url,     # must be one of the registered post-logout URIs
+    state: SecureRandom.hex(8)
+  )
+  render :signing_out                 # a view with an auto-submitting POST form
+end
+```
+
+```erb
+<%# app/views/sessions/signing_out.html.erb %>
+<%= form_tag @logout.endpoint, method: :post, id: "hub-logout" do %>
+  <% @logout.params.each do |name, value| %><%= hidden_field_tag name, value %><% end %>
+<% end %>
+<script>document.getElementById("hub-logout").submit()</script>
+```
+
+`end_session` discovers the endpoint from the Hub (it does not hard-code it). When a plain
+redirect is acceptable and the ID token in the URL is not a concern, `@logout.redirect_url`
+is the endpoint with the fields in the query string instead.
+
 ## API
 
 ```ruby
@@ -91,6 +128,8 @@ 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.checkout("org_01J...", plan: "pro", success_url: done_url, cancel_url: billing_url)["url"]
+hub.portal("org_01J...", return_url: billing_url)["url"]   # "Manage billing"
 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

data/lib/iorwerth/hub/client.rb

@@ -23,6 +23,8 @@ module Iorwerth
         "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"],
+        "checkout" => [:post, "/api/v1/organizations/{organization_id}/checkout"],
+        "portal" => [:post, "/api/v1/organizations/{organization_id}/portal"],
         "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"],
@@ -74,6 +76,19 @@ module Iorwerth
                               idempotency_key: idempotency_key)
       end
 
+      # A Stripe Checkout page for one of this product's plans; without plan:, the one requested
+      # at signup. Redirect the customer to answer["url"].
+      def checkout(organization_id, success_url:, cancel_url:, plan: nil, idempotency_key: SecureRandom.uuid)
+        body = { plan: plan, success_url: success_url, cancel_url: cancel_url }.compact
+        call("checkout", organization_id: organization_id, body: body, idempotency_key: idempotency_key)
+      end
+
+      # A Stripe Customer Portal page: card, invoices, plan changes, cancellation.
+      def portal(organization_id, return_url:, idempotency_key: SecureRandom.uuid)
+        call("portal", organization_id: organization_id, body: { return_url: return_url },
+                       idempotency_key: idempotency_key)
+      end
+
       def get_usage(organization_id)
         call("get_usage", organization_id: organization_id)
       end

data/lib/iorwerth/hub/logout.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Iorwerth
+  module Hub
+    # RP-initiated logout (OpenID Connect RP-Initiated Logout 1.0): end the Hub session when a
+    # product signs someone out. Clear the product's own session first, then send the browser
+    # to the Hub's end-session endpoint. POST it (`endpoint` + `params`) so the ID token stays
+    # out of URLs and server logs; the Hub returns the browser to `redirect_uri` with `state`
+    # unchanged, so a product can carry its own return target through the round trip.
+    #
+    #   logout = Iorwerth::Hub.end_session(id_token: session[:hub_id_token],
+    #                                      redirect_uri: signed_out_url, state: SecureRandom.hex)
+    #   # an auto-submitting POST form in the view:
+    #   form_tag logout.endpoint, method: :post do
+    #     safe_join(logout.params.map { |name, value| hidden_field_tag(name, value) })
+    #   end
+    class EndSession
+      attr_reader :id_token, :redirect_uri, :state, :client_id
+
+      def initialize(id_token:, redirect_uri: nil, state: nil,
+                     client_id: Hub.config.oidc_client_id, url: Hub.config.url)
+        @id_token = id_token
+        @redirect_uri = redirect_uri
+        @state = state
+        @client_id = client_id
+        @url = url
+      end
+
+      # The Hub's end-session endpoint, from its discovery document.
+      def endpoint
+        Hub.discovery(@url).fetch("end_session_endpoint")
+      end
+
+      # The logout request's fields, for a POST form. Absent ones are dropped.
+      def params
+        {
+          "id_token_hint" => id_token,
+          "client_id" => client_id,
+          "post_logout_redirect_uri" => redirect_uri,
+          "state" => state
+        }.compact
+      end
+
+      # The endpoint with the fields in the query string, for a plain redirect. Prefer a POST
+      # of `endpoint` + `params` when the ID token should not appear in a URL.
+      def redirect_url
+        uri = URI(endpoint)
+        uri.query = URI.encode_www_form(params)
+        uri.to_s
+      end
+    end
+  end
+end

data/lib/iorwerth/hub/version.rb

@@ -2,6 +2,6 @@
 
 module Iorwerth
   module Hub
-    VERSION = "0.1.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/iorwerth/hub.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
 require "iorwerth/hub/version"
 require "iorwerth/hub/errors"
 require "iorwerth/hub/configuration"
 require "iorwerth/hub/client"
 require "iorwerth/hub/entitlements"
+require "iorwerth/hub/logout"
 require "iorwerth/hub/webhook"
 
 module Iorwerth
@@ -48,9 +54,38 @@ module Iorwerth
         info.fetch("organizations", info.fetch(:organizations, []))
       end
 
+      # Build an RP-initiated logout for one person's session. See EndSession.
+      def end_session(id_token:, redirect_uri: nil, state: nil)
+        EndSession.new(id_token: id_token, redirect_uri: redirect_uri, state: state)
+      end
+
+      # The Hub's OpenID Connect discovery document, fetched once per URL and cached.
+      def discovery(url = config.url)
+        raise ConfigurationError, "Set HUB_URL." if url.nil? || url.empty?
+
+        (@discovery ||= {})[url] ||= fetch_discovery(url)
+      end
+
       # Forget settings and cached state; for tests.
       def reset!
-        @config = @client = @entitlements = nil
+        @config = @client = @entitlements = @discovery = nil
+      end
+
+      private
+
+      def fetch_discovery(url)
+        uri = URI("#{url.chomp('/')}/.well-known/openid-configuration")
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: config.open_timeout,
+                                                       read_timeout: config.timeout) do |http|
+          request = Net::HTTP::Get.new(uri)
+          request["Accept"] = "application/json"
+          request["User-Agent"] = "iorwerth-hub-ruby/#{VERSION}"
+          http.request(request)
+        end
+        JSON.parse(response.body)
+      rescue SocketError, SystemCallError, Timeout::Error, IOError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError, "#{uri.host}: #{e.class}: #{e.message}"
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iorwerth-hub
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Iorwerth Technologies
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-10 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.
@@ -25,6 +25,7 @@ files:
 - lib/iorwerth/hub/configuration.rb
 - lib/iorwerth/hub/entitlements.rb
 - lib/iorwerth/hub/errors.rb
+- lib/iorwerth/hub/logout.rb
 - lib/iorwerth/hub/omniauth.rb
 - lib/iorwerth/hub/version.rb
 - lib/iorwerth/hub/webhook.rb