omniauth-honin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ba9cb60419c162b8451a3fcb5b2071ac8d5229638d98422b93dbfa9f02e4666
+  data.tar.gz: 43893c67e00b951e240e352c2d08f287d2dcadcb85820d00301c9e6cb7c0a479
+SHA512:
+  metadata.gz: e3aead620f5c9a95604c2714811558d783fadc3940ac29c63f6e8c441c67e414977c7174a9db5686edb9ed7743ee67dc6d5809b4e57874c99bf83d8233ba102a
+  data.tar.gz: 0a5bdaa70720965c09c80ba533ce5ea47fa18d11c55fd9fcc2f4279f59b29c1add213dd19aeaf8404f62fe093d82fbdcf3d1e8d41398b8b824e1659eb842e5fa

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axel Gustav
+
+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,120 @@
+# omniauth-honin
+
+An OmniAuth strategy for authenticating users via [Honin](https://honin.id) — the privacy-first identity provider.
+
+Works with Honin Cloud (`honin.id`), self-hosted Honin instances, and Rails apps that mount the `honin-engine` in IDP mode.
+
+## Installation
+
+```ruby
+gem "omniauth-honin"
+```
+
+## Configuration
+
+### Honin Cloud
+
+```ruby
+# config/initializers/omniauth.rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :honin,
+    ENV["HONIN_CLIENT_ID"],
+    ENV["HONIN_CLIENT_SECRET"],
+    jwks_uri: "https://honin.id/.well-known/jwks.json"
+end
+```
+
+`jwks_uri` is optional but recommended for production — it verifies the JWT signature on every login. Without it the access token is decoded without signature verification.
+
+### Self-hosted instance (root-mounted)
+
+Point `client_options: { site: }` at your server. Everything else is the same.
+
+```ruby
+provider :honin,
+  ENV["HONIN_CLIENT_ID"],
+  ENV["HONIN_CLIENT_SECRET"],
+  client_options: { site: "https://auth.acme.co" },
+  jwks_uri: "https://auth.acme.co/.well-known/jwks.json"
+```
+
+### Self-hosted instance (sub-path mount)
+
+If the Honin engine is mounted under a path — e.g. `mount HoninEngine, at: "/auth"` — set `base_path` to that path. The strategy uses it to construct the OAuth endpoints and to verify the `iss` claim in the JWT.
+
+```ruby
+provider :honin,
+  ENV["HONIN_CLIENT_ID"],
+  ENV["HONIN_CLIENT_SECRET"],
+  client_options: { site: "https://id.acme.co" },
+  base_path: "/auth",
+  jwks_uri: "https://id.acme.co/auth/.well-known/jwks.json"
+```
+
+`base_path` is not needed for Honin Cloud or any instance where the engine is at the root.
+
+### Requesting additional scopes
+
+Honin supports `email`, `profile`, `timezone`, and `locale`. Scopes must be registered on your Honin Application. The default is `"email profile"`.
+
+```ruby
+provider :honin,
+  ENV["HONIN_CLIENT_ID"],
+  ENV["HONIN_CLIENT_SECRET"],
+  scope: "email profile timezone locale"
+```
+
+## Auth hash
+
+After successful authentication, `request.env["omniauth.auth"]` contains:
+
+```json
+{
+  "provider": "honin",
+  "uid": "abc123xyz456def789",
+  "info": {
+    "account_type": "standard",
+    "name": "Jane Doe",
+    "email": "jane@example.com",
+    "email_verified": true,
+    "timezone": "America/Toronto",
+    "locale": "en"
+  },
+  "credentials": {
+    "token": "eyJhbGciOiJSUzI1NiIs...",
+    "token_type": "Bearer",
+    "expires": true,
+    "expires_at": 1700000000
+  },
+  "extra": {
+    "raw_info": { "...JWT claims..." },
+    "granted_scopes": ["email", "profile"],
+    "required_scopes": ["email"]
+  }
+}
+```
+
+`account_type` is `"anonymous"` for anonymous users; scope-dependent fields (`name`, `email`, etc.) are absent.
+
+`granted_scopes` reflects what the user actually granted. `required_scopes` are scopes the Honin Application marked as non-deniable.
+
+## How it works
+
+1. Strategy generates a PKCE code verifier/challenge pair (S256).
+2. User is redirected to the Honin authorize endpoint.
+3. User authenticates and grants consent.
+4. Honin redirects back with an authorization code.
+5. Strategy exchanges the code (with PKCE verifier) for a signed JWT access token.
+6. Strategy decodes the JWT to extract user claims — no separate userinfo request needed.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec standardrb
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/omniauth/honin/version.rb

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

data/lib/omniauth/strategies/honin.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "omniauth"
+require "omniauth-oauth2"
+require "jwt"
+require "securerandom"
+require "base64"
+require "digest"
+require "net/http"
+require "uri"
+require "json"
+
+module OmniAuth
+  module Strategies
+    class Honin < OmniAuth::Strategies::OAuth2
+      option :name, "honin"
+
+      option :client_options,
+        site: "https://honin.id",
+        authorize_url: "/oauth/authorize",
+        token_url: "/oauth/token"
+
+      # Disabled so we own the full PKCE flow; omniauth-oauth2's built-in
+      # implementation would conflict with our session keys and S256 enforcement.
+      option :pkce, false
+
+      option :scope, "email profile"
+
+      # Honin only supports client_secret_post, not client_secret_basic.
+      option :auth_token_params, {client_secret_param: "client_secret"}
+
+      # Sub-path mount support. Set to the engine's mount path when the Honin
+      # instance is not at the root — e.g. "/auth" for id.acme.co/auth/...
+      # The issuer claim in the JWT is verified against site + base_path.
+      # Leave empty (default) for honin.id and root-mounted instances.
+      option :base_path, ""
+
+      option :jwks_uri, nil
+      option :jwks, nil
+
+      PKCE_VERIFIER_LENGTH = 64
+
+      def request_phase
+        generate_pkce!
+        super
+      end
+
+      def authorize_params
+        super.tap do |params|
+          params[:code_challenge] = session[:honin_pkce_challenge]
+          params[:code_challenge_method] = "S256"
+        end
+      end
+
+      def token_params
+        super.tap do |params|
+          params[:code_verifier] = session[:honin_pkce_verifier]
+        end
+      end
+
+      def callback_phase
+        super
+      ensure
+        clear_pkce_session!
+      end
+
+      uid { decoded_jwt["sub"] }
+
+      info do
+        jwt = decoded_jwt
+        {
+          account_type: jwt["account_type"],
+          name: jwt["display_name"],
+          email: jwt["email"],
+          email_verified: jwt["email_verified"],
+          timezone: jwt["timezone"],
+          locale: jwt["locale"]
+        }.compact
+      end
+
+      extra do
+        jwt = decoded_jwt
+        {
+          raw_info: raw_info,
+          granted_scopes: jwt["granted_scopes"],
+          required_scopes: jwt["required_scopes"]
+        }.compact
+      end
+
+      def client
+        @client ||= ::OAuth2::Client.new(options.client_id, options.client_secret,
+          site: options.client_options.site,
+          authorize_url: "#{options.base_path}/oauth/authorize",
+          token_url: "#{options.base_path}/oauth/token")
+      end
+
+      def raw_info
+        @raw_info ||= decoded_jwt
+      end
+
+      def decoded_jwt
+        @decoded_jwt ||= begin
+          token = access_token.token
+
+          if jwks_verification_available?
+            decode_verified_jwt(token)
+          else
+            decode_unverified_jwt(token)
+          end
+        end
+      end
+
+      private
+
+      def generate_pkce!
+        verifier = SecureRandom.urlsafe_base64(PKCE_VERIFIER_LENGTH)
+        challenge = Base64.urlsafe_encode64(
+          Digest::SHA256.digest(verifier),
+          padding: false
+        )
+
+        session[:honin_pkce_verifier] = verifier
+        session[:honin_pkce_challenge] = challenge
+      end
+
+      def clear_pkce_session!
+        session.delete(:honin_pkce_verifier)
+        session.delete(:honin_pkce_challenge)
+      end
+
+      def jwks_verification_available?
+        (options.jwks_uri && !options.jwks_uri.to_s.empty?) ||
+          (!options.jwks.nil? && options.jwks != false)
+      end
+
+      def decode_verified_jwt(token)
+        decode_opts = {
+          algorithms: ["RS256"],
+          verify_iss: true,
+          iss: "#{options.client_options.site}#{options.base_path}",
+          verify_aud: true,
+          aud: options.client_id
+        }
+
+        payload, = JWT.decode(token, nil, true, decode_opts.merge(jwks: resolve_jwk_set))
+        payload
+      rescue JWT::DecodeError, JWT::VerificationError, JWT::ExpiredSignature,
+        JWT::InvalidIssuerError, JWT::JWKError => e
+        raise OmniAuth::Strategies::OAuth2::CallbackError.new(:jwt_verification_failed, e.message)
+      end
+
+      def decode_unverified_jwt(token)
+        payload, = JWT.decode(token, nil, false)
+        payload
+      end
+
+      def resolve_jwk_set
+        if options.jwks_uri && !options.jwks_uri.to_s.empty?
+          fetch_jwks(options.jwks_uri)
+        else
+          coerce_jwks(options.jwks)
+        end
+      end
+
+      def coerce_jwks(jwks)
+        case jwks
+        when JWT::JWK::Set
+          jwks
+        when Hash
+          JWT::JWK::Set.new(jwks[:keys] || jwks["keys"] || [jwks])
+        when Array
+          JWT::JWK::Set.new(jwks)
+        else
+          raise ArgumentError, "jwks must be a Hash, Array, or JWT::JWK::Set, got #{jwks.class}"
+        end
+      end
+
+      def fetch_jwks(uri)
+        response = Net::HTTP.get_response(URI.parse(uri))
+        unless response.is_a?(Net::HTTPSuccess)
+          raise OmniAuth::Strategies::OAuth2::CallbackError.new(
+            :jwks_fetch_failed, "HTTP #{response.code}"
+          )
+        end
+        body = JSON.parse(response.body)
+        JWT::JWK::Set.new(body["keys"] || [body])
+      rescue JSON::ParserError, JWT::JWKError => e
+        raise OmniAuth::Strategies::OAuth2::CallbackError.new(:jwks_fetch_failed, e.message)
+      end
+    end
+  end
+end

data/lib/omniauth-honin.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omniauth/honin/version"
+require "omniauth/strategies/honin"

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-honin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Axel Gustav
+bindir: exe
+cert_chain: []
+date: 2026-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.22'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: An OmniAuth strategy for authenticating users via the Honin identity
+  provider. Supports Honin Cloud (honin.id), self-hosted Honin instances, and apps
+  that mount the honin-engine in IDP mode.
+email:
+- dev@axelgustav.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omniauth-honin.rb
+- lib/omniauth/honin/version.rb
+- lib/omniauth/strategies/honin.rb
+homepage: https://codefloe.com/GusTech/omniauth-honin
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://honin.id/developers
+  source_code_uri: https://codefloe.com/GusTech/omniauth-honin
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Honin OAuth2 strategy for OmniAuth
+test_files: []