vert-core 1.0.12 → 1.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ae6a0dbd4ab8e8531cae0d3ac0bab155efcdc3b05d7deeebc1d8960296e0cff
-  data.tar.gz: 573c33470d90dd165f78434919fef156bc55f05e955991e624ba2aae8357ff43
+  metadata.gz: efcc19b5c1872506cb9d75e59020db09984c94d24cd690709c26db3c4f966194
+  data.tar.gz: a21f57805634a5f6fbb14bfcf6513c92382309d2ee004f73c955e997a7f7b932
 SHA512:
-  metadata.gz: 382265549bfa3ae6806f5fba101cc7ff59765c428b1cb0553f13164c2b6dbcd1d114f95f24649b4bd6213604a063eda5728c08b5e2da8998a4adfa4951f83589
-  data.tar.gz: e43a3dd92ab7900d34baff3cf7ac831d3604a0cc5c583f8fcba1ce39c6b56175afb48d26b9cd65b1294d6928eda8553eb9faaafd49e6dc7de22fe800071c7b0a
+  metadata.gz: 8fe2af573b8f87f8ee20c65944a9aa1fc74c0f3ceab41ae355d627d41d294d1c90e195fd77c0ae2a2813d6bbdf8638ac6c5f724beee917b0d21e1527eb75c54e
+  data.tar.gz: 709adf6c940017b3cf322a35d810cedff4fe73126c5e3483668592cb21cfffb830d0889b09ddd791fd95c2bdbc7508cad129b4d67bfe3adbb68caf49fc5176e2

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [1.0.13] - 2026-05-24
+
+### Added
+
+- `Vert::Auth::JwtAuthenticatable`: nova concern de autenticação JWT Bearer que estabelece o contexto multi-tenant via `Vert::Current` lendo **exclusivamente** os claims do JWT (regra inviolável 2 do projeto — nunca confiar em parâmetros do cliente).
+  - Valida o header `X-Tenant-ID` (defesa em profundidade): se presente, precisa ser igual ao `tenant_id` do JWT, caso contrário responde **403 Forbidden** e dispara o hook `on_tenant_mismatch` (override-able por serviço para gravar em `audit_logs`).
+  - Header ausente → JWT manda silenciosamente.
+  - Hooks override-áveis: `jwt_secret`, `jwt_algorithm`, `tenant_header_name`, `on_tenant_mismatch`, `on_jwt_invalid`, `current_jwt_user`.
+  - `skip_jwt_authentication` para opt-out em endpoints públicos (ex: `/auth/sign_in`, `/health`).
+  - Opt-in via `Vert.config.enable_jwt_auth = true` no initializer.
+- `Configuration#enable_jwt_auth`: nova flag (default `false`).
+
+### Migration guide
+
+```ruby
+# config/initializers/vert.rb
+Vert.configure { |c| c.enable_jwt_auth = true }
+
+# app/controllers/api/base_controller.rb
+class Api::BaseController < ApplicationController
+  include Vert::Auth::JwtAuthenticatable
+
+  # opcional: gravar mismatch em audit_logs
+  def on_tenant_mismatch(jwt_tenant_id:, header_tenant_id:, user_id:)
+    super
+    AuditLog.create!(
+      event_type: "security.tenant_mismatch",
+      user_id: user_id,
+      payload: { jwt: jwt_tenant_id, header: header_tenant_id,
+                 ip: request.remote_ip, path: request.fullpath }
+    )
+  end
+end
+```
+
+Corrige fragmentação dos 5 patterns de auth JWT distribuídos pelos 23 serviços do monorepo (alguns aceitavam `X-Tenant-ID` como fallback ou — pior — como fonte primária, sobrescrevendo o JWT).
+
 ## [1.0.7] - 2026-03-21
 
 ### Added

data/lib/vert/auth/jwt_authenticatable.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Vert
+  module Auth
+    # JwtAuthenticatable
+    # ------------------
+    # Concern para controllers Rails que autenticam via JWT Bearer e estabelecem
+    # contexto multi-tenant através de Vert::Current.
+    #
+    # Política de segurança (regra invioláv. 2 do projeto):
+    # - tenant_id, company_id e user_id SÃO LIDOS APENAS DO JWT.
+    # - O header `X-Tenant-ID`, quando presente, é tratado como defesa em
+    #   profundidade: precisa ser igual ao `tenant_id` do JWT, senão a request
+    #   é rejeitada com 403 (potencial tentativa cross-tenant).
+    # - Se o header estiver ausente, o JWT manda silenciosamente.
+    #
+    # Uso típico:
+    #
+    #   # config/initializers/vert.rb
+    #   Vert.configure { |c| c.enable_jwt_auth = true }
+    #
+    #   # app/controllers/api/base_controller.rb
+    #   class Api::BaseController < ApplicationController
+    #     include Vert::Auth::JwtAuthenticatable
+    #   end
+    #
+    # Opt-out por controller:
+    #
+    #   class Api::PublicController < Api::BaseController
+    #     skip_jwt_authentication
+    #   end
+    #
+    # Hooks override-áveis (por serviço):
+    #
+    #   - `jwt_secret`           → default `ENV["JWT_SECRET"]`
+    #   - `jwt_algorithm`        → default `ENV.fetch("JWT_ALGORITHM", "HS256")`
+    #   - `tenant_header_name`   → default `"X-Tenant-ID"`
+    #   - `on_tenant_mismatch`   → default só faz `Rails.logger.warn`. Cada
+    #                              serviço pode override para gravar em
+    #                              `audit_logs` / `security_events`.
+    #   - `on_jwt_invalid`       → default `Rails.logger.warn`.
+    #   - `current_jwt_user`     → default `nil`. Serviços que tenham model
+    #                              `User` podem retornar o registro para uso
+    #                              em controllers.
+    module JwtAuthenticatable
+      extend ActiveSupport::Concern
+
+      class Error < StandardError; end
+      class MissingTokenError < Error; end
+      class InvalidTokenError < Error; end
+      class TenantMismatchError < Error; end
+
+      included do
+        before_action :authenticate_jwt!
+      end
+
+      class_methods do
+        # Permite que um controller filho opt-out do filtro
+        # (ex: endpoints públicos como /auth/sign_in, /health).
+        def skip_jwt_authentication(**options)
+          skip_before_action :authenticate_jwt!, **options
+        end
+      end
+
+      private
+
+      def authenticate_jwt!
+        token = extract_bearer_token
+        if token.blank?
+          render_jwt_error(:unauthorized, "Missing authorization token")
+          return
+        end
+
+        @jwt_payload = decode_jwt(token)
+        if @jwt_payload.nil?
+          render_jwt_error(:unauthorized, "Invalid or expired token")
+          return
+        end
+
+        jwt_tenant_id   = @jwt_payload["tenant_id"]
+        header_tenant   = request.headers[tenant_header_name].presence
+
+        if header_tenant.present? && jwt_tenant_id.present? &&
+           header_tenant.to_s != jwt_tenant_id.to_s
+          on_tenant_mismatch(
+            jwt_tenant_id: jwt_tenant_id,
+            header_tenant_id: header_tenant,
+            user_id: @jwt_payload["sub"]
+          )
+          render_jwt_error(:forbidden, "Tenant header mismatch")
+          return
+        end
+
+        Vert::Current.set_context(
+          tenant_id:  jwt_tenant_id,
+          company_id: @jwt_payload["company_id"],
+          user_id:    @jwt_payload["sub"],
+          request_id: request.request_id
+        )
+
+        true
+      end
+
+      def extract_bearer_token
+        header = request.headers["Authorization"]
+        return nil unless header.is_a?(String) && header.start_with?("Bearer ")
+
+        header.split(" ", 2).last.to_s.strip.presence
+      end
+
+      def decode_jwt(token)
+        require "jwt" unless defined?(JWT)
+
+        ::JWT.decode(
+          token,
+          jwt_secret,
+          true,
+          algorithm: jwt_algorithm
+        ).first
+      rescue ::JWT::DecodeError, ::JWT::ExpiredSignature, ::JWT::VerificationError => e
+        on_jwt_invalid(error: e)
+        nil
+      rescue LoadError
+        Rails.logger.error("[Vert::Auth] gem 'jwt' não carregada — adicione `gem \"jwt\"` ao Gemfile do serviço")
+        nil
+      end
+
+      def jwt_secret
+        ENV.fetch("JWT_SECRET")
+      end
+
+      def jwt_algorithm
+        ENV.fetch("JWT_ALGORITHM", "HS256")
+      end
+
+      def tenant_header_name
+        "X-Tenant-ID"
+      end
+
+      # Hook: chamado quando header X-Tenant-ID diverge do JWT.
+      # Override em ApplicationController para gravar em audit_logs:
+      #
+      #   def on_tenant_mismatch(jwt_tenant_id:, header_tenant_id:, user_id:)
+      #     super
+      #     AuditLog.create!(
+      #       event_type: "security.tenant_mismatch",
+      #       user_id: user_id,
+      #       payload: { jwt_tenant_id:, header_tenant_id:, ip: request.remote_ip, path: request.fullpath }
+      #     )
+      #   end
+      def on_tenant_mismatch(jwt_tenant_id:, header_tenant_id:, user_id:)
+        Rails.logger.warn(
+          "[Vert::Auth] Tenant mismatch: " \
+          "user=#{user_id} jwt=#{jwt_tenant_id} header=#{header_tenant_id} " \
+          "ip=#{request.remote_ip} path=#{request.fullpath}"
+        )
+      end
+
+      def on_jwt_invalid(error:)
+        Rails.logger.warn("[Vert::Auth] JWT decode error: #{error.class}: #{error.message}")
+      end
+
+      def render_jwt_error(status, message)
+        render json: { error: message }, status: status
+      end
+
+      # Payload bruto do JWT (claims), disponível nos controllers
+      # após `authenticate_jwt!`.
+      def current_jwt_payload
+        @jwt_payload
+      end
+
+      # Override no serviço para retornar o registro User correspondente
+      # ao `sub` do JWT.
+      def current_jwt_user
+        nil
+      end
+    end
+  end
+end

data/lib/vert/configuration.rb

@@ -16,6 +16,7 @@ module Vert
                   :enable_outbox,
                   :enable_health,
                   :enable_authorization,
+                  :enable_jwt_auth,
                   :enable_multi_tenant,
                   :enable_auditable,
                   :enable_soft_deletable,
@@ -43,6 +44,7 @@ module Vert
       @enable_outbox = false
       @enable_health = true
       @enable_authorization = false
+      @enable_jwt_auth = false
       @enable_multi_tenant = false
       @enable_auditable = false
       @enable_soft_deletable = false

data/lib/vert/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vert
-  VERSION = "1.0.12"
+  VERSION = "1.0.13"
 end

data/lib/vert.rb

@@ -36,6 +36,9 @@ require_relative "vert/authorization/dynamic_policy"
 require_relative "vert/authorization/policy_finder"
 require_relative "vert/authorization/controller_methods"
 
+# Auth
+require_relative "vert/auth/jwt_authenticatable"
+
 # Railtie
 require_relative "vert/railtie" if defined?(Rails::Railtie)
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vert-core
 version: !ruby/object:Gem::Version
-  version: 1.0.12
+  version: 1.0.13
 platform: ruby
 authors:
 - Vert Team
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -180,6 +180,7 @@ files:
 - README.md
 - SECURITY_AND_QUALITY_AUDIT.md
 - lib/vert.rb
+- lib/vert/auth/jwt_authenticatable.rb
 - lib/vert/authorization/controller_methods.rb
 - lib/vert/authorization/dynamic_policy.rb
 - lib/vert/authorization/permission_resolver.rb
@@ -237,7 +238,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Generic core library for Rails microservices
 test_files: []