openehr-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47f141ace236ed8735976a2ea1dcf01d2e05275d9ae82f18448659198f0f6c29
-  data.tar.gz: 9f75fe85bf8a55fbf723d3d61e100ae5d270fdc35413e9acd79fe0fd8c9f2f4b
+  metadata.gz: 8420a812bd6c4b3f95a403f4804fa58d660a1aa6d736d106bc0dc57a8b63e1ee
+  data.tar.gz: df4f5629f4915f03c4a07b944a168a1c53d08da043e07cbc6cf6d705d036f017
 SHA512:
-  metadata.gz: 0fe633b32659bc45213734d878c3d1e958fdb1dda8f7c71f93fc299ac6004d78c525f5d44b44b00b5746241d366d1bcdaca1e702c6189720de974e9d300fdf5e
-  data.tar.gz: bda15de876019effa3d914cb969748d3912dcd8af682dba34faf8acb08844243e9083aea2fb4c62ad3aa6385c778be82250913d57dbd4d77a2000d016834f909
+  metadata.gz: 0e39f211e2243b0ac74aff1408136652ba0b4f829a8bc28a92a842ba3e1636955d4ea9fcdfe6ee0e0351b9f3c7c5bd763139478574a5d5acf19c8f8fb9f62a5a
+  data.tar.gz: 4a8e6beb226a33825df8cd1d762b546cbaf4ca39877d2bda72ab8e81978a58fe57ceefa75ef1d372c609d495fb6d35adc65016592078d10f746be0f7ca041ed7

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-08-13
+
+### Added
+- `OpenehrRails.authenticate_with`: a pluggable authentication hook, run
+  as a `before_action` ahead of every engine action (admin UI, AQL
+  console, patient timeline, the `/v1` openEHR REST API, and the `/fhir`
+  facade). Host apps wire in their own mechanism (Devise, HTTP token,
+  anything) with the controller as context. Per-surface differentiation
+  via `openehr_access_scope` (`:admin`/`:rest_api`/`:fhir`).
+- `OpenehrRails.allow_unauthenticated_access`: explicit opt-out for
+  intentionally-open deployments.
+
+### Changed (behavior change -- read before upgrading)
+- **The engine now denies all requests with `403 Forbidden` outside the
+  `development` and `test` environments unless `authenticate_with` or
+  `allow_unauthenticated_access` is configured.** Previously every
+  engine route (including the full openEHR REST API and the FHIR
+  facade's create endpoint) was open with no access control whatsoever.
+  Apps running 0.3.0 in production must configure one of the two before
+  upgrading, or the engine will start responding 403 to everything.
+- `RemoteFetcher` now also rejects loopback/private/link-local (including
+  cloud metadata) addresses, both on the initial URL and on every
+  redirect hop, closing an SSRF gap (previously only the URL scheme was
+  validated).
+- Every generic `rescue_from StandardError` handler across the engine's
+  controllers now logs the exception (class, message, and a short
+  backtrace) via `Rails.logger` before responding -- previously errors
+  were rendered to the client and left no server-side trace at all.
+
 ## [0.3.0] - 2026-08-13
 
 ### Added

data/README.md

@@ -65,6 +65,61 @@ enabled in the development environment only. Override with:
 OpenehrRails.enable_runtime_scaffolding = true # or false
 ```
 
+### Authentication
+
+Everything the engine serves — the template admin UI, the AQL console,
+the patient timeline, the openEHR REST API (`/openehr/v1`) and the FHIR
+facade (`/openehr/fhir`) — handles clinical data, so outside the
+`development` and `test` environments the engine is **closed by
+default**: every request gets `403 Forbidden` until you configure an
+authentication hook.
+
+The hook runs as a `before_action` inside the engine controller handling
+the request (`instance_exec`'d, so it can use `request`, `render`,
+`redirect_to`, and any helper your app mixes into `ActionController::Base`).
+Deny by rendering or redirecting — a hook that raises would be caught
+and reported as a misleading error by some engine controllers'
+`rescue_from StandardError`.
+
+```ruby
+# config/initializers/openehr.rb
+
+# Devise:
+OpenehrRails.authenticate_with = -> { authenticate_user! }
+
+# Bearer token:
+OpenehrRails.authenticate_with = lambda do
+  authenticate_or_request_with_http_token do |token, _options|
+    ActiveSupport::SecurityUtils.secure_compare(
+      token, Rails.application.credentials.openehr_api_token.to_s
+    )
+  end
+end
+```
+
+To use a different mechanism per surface, branch on `openehr_access_scope`
+(`:admin` — template UI / AQL console / timeline, `:rest_api` — `/v1`,
+`:fhir` — the FHIR facade):
+
+```ruby
+OpenehrRails.authenticate_with = lambda do
+  case openehr_access_scope
+  when :admin then authenticate_user!
+  else authenticate_or_request_with_http_token { |t, _| valid_api_token?(t) }
+  end
+end
+```
+
+To intentionally run without authentication (e.g. behind a reverse
+proxy that already authenticates, or a network-isolated internal app):
+
+```ruby
+OpenehrRails.allow_unauthenticated_access = true
+```
+
+Note: the JSON API controllers (`/v1`, `/fhir`) skip CSRF protection, so
+prefer token authentication over session cookies for those.
+
 ### HL7 FHIR R5 facade
 
 The engine also serves a FHIR R5 API under `<mount>/fhir`

data/app/controllers/openehr_rails/application_controller.rb

@@ -3,5 +3,42 @@
 module OpenehrRails
   class ApplicationController < ActionController::Base
     layout 'openehr_rails/application'
+
+    before_action :authenticate_openehr_access!
+
+    # Which engine surface this request targets, so a single
+    # OpenehrRails.authenticate_with hook can differentiate if desired:
+    #   :admin    - template management UI, AQL console, patient timeline
+    #   :rest_api - openEHR REST API under /v1
+    #   :fhir     - HL7 FHIR R5 facade under /fhir
+    def openehr_access_scope
+      :admin
+    end
+
+    private
+
+    def authenticate_openehr_access!
+      hook = OpenehrRails.authenticate_with
+      return instance_exec(&hook) if hook
+      return if OpenehrRails.unauthenticated_access_allowed?
+
+      deny_openehr_access
+    end
+
+    def log_openehr_error(error)
+      Rails.logger&.error(
+        "[OpenehrRails] #{error.class}: #{error.message}\n#{Array(error.backtrace).first(10).join("\n")}"
+      )
+    end
+
+    def deny_openehr_access
+      message = 'openEHR engine access denied: no authentication configured. ' \
+                'Set OpenehrRails.authenticate_with in config/initializers/openehr.rb.'
+      if request.format.json?
+        render json: { error: message }, status: :forbidden
+      else
+        render plain: message, status: :forbidden
+      end
+    end
   end
 end

data/app/controllers/openehr_rails/fhir_controller.rb

@@ -15,6 +15,10 @@ module OpenehrRails
 
     FHIR_CONTENT_TYPE = 'application/fhir+json'
 
+    def openehr_access_scope
+      :fhir
+    end
+
     def metadata
       render_fhir OpenehrRails::Fhir::CapabilityStatement.build(base_url: request.base_url)
     end
@@ -125,6 +129,7 @@ module OpenehrRails
     end
 
     def render_operation_outcome(error)
+      log_openehr_error(error)
       status = case error
                when OpenehrRails::Fhir::Deserializer::UnmappedResource then :unprocessable_entity
                when ActiveRecord::RecordInvalid then :unprocessable_entity

data/app/controllers/openehr_rails/openehr_api/compositions_controller.rb

@@ -20,6 +20,10 @@ module OpenehrRails
       rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
       rescue_from PreconditionFailed, with: :render_precondition_failed
 
+      def openehr_access_scope
+        :rest_api
+      end
+
       # POST /v1/ehr/:ehr_id/composition
       def create
         ehr = find_ehr!
@@ -110,6 +114,7 @@ module OpenehrRails
       end
 
       def render_error(error)
+        log_openehr_error(error)
         render json: { error: error.message }, status: :bad_request
       end
     end

data/app/controllers/openehr_rails/openehr_api/ehrs_controller.rb

@@ -11,6 +11,10 @@ module OpenehrRails
       rescue_from ActiveRecord::RecordInvalid, with: :render_invalid
       rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
 
+      def openehr_access_scope
+        :rest_api
+      end
+
       # POST /v1/ehr  (server-generated ehr_id)
       def create
         ehr = OpenehrRails::Rm::Ehr.create!(ehr_attributes.merge(ehr_id: SecureRandom.uuid))
@@ -75,6 +79,7 @@ module OpenehrRails
       end
 
       def render_error(error)
+        log_openehr_error(error)
         render json: { error: error.message }, status: :bad_request
       end
     end

data/app/controllers/openehr_rails/queries_controller.rb

@@ -11,6 +11,10 @@ module OpenehrRails
     rescue_from StandardError, with: :render_error
     rescue_from OpenehrRails::Aql::Error, with: :render_aql_error
 
+    def openehr_access_scope
+      action_name == 'execute' ? :rest_api : :admin
+    end
+
     # GET /query -- HTML console. Executes via fetch against
     # POST /v1/query/aql below, so there is exactly one execution path.
     def show; end
@@ -50,6 +54,7 @@ module OpenehrRails
     end
 
     def render_error(error)
+      log_openehr_error(error)
       render json: { error: error.message }, status: :bad_request
     end
   end

data/app/controllers/openehr_rails/templates_controller.rb

@@ -30,6 +30,7 @@ module OpenehrRails
         redirect_to root_path, notice: "Generated UI at /#{result.route_path}"
       end
     rescue StandardError => e
+      log_openehr_error(e)
       redirect_to root_path, alert: "Generation failed: #{e.message}"
     end
 

data/lib/generators/openehr/install/templates/initializers/openehr.rb

@@ -20,3 +20,34 @@ require 'openehr_rails'
 # OpenehrRails.default_category = %w[433 event]  # [code, value]
 # OpenehrRails.default_composer_name = 'unknown'
 # OpenehrRails.default_encoding = 'UTF-8'
+
+# Authentication (REQUIRED before deploying outside development/test):
+# the engine (admin UI, AQL console, /v1 REST API, /fhir facade) serves
+# clinical data, so it denies every request with 403 in any environment
+# other than development/test until you configure a hook here. The hook
+# runs as a before_action inside the engine controller handling the
+# request (instance_exec'd) -- deny by rendering/redirecting, not
+# raising, since some engine controllers rescue_from StandardError.
+#
+# Devise:
+# OpenehrRails.authenticate_with = -> { authenticate_user! }
+#
+# Bearer token:
+# OpenehrRails.authenticate_with = lambda do
+#   authenticate_or_request_with_http_token do |token, _options|
+#     ActiveSupport::SecurityUtils.secure_compare(
+#       token, Rails.application.credentials.openehr_api_token.to_s
+#     )
+#   end
+# end
+#
+# Different mechanism per surface (openehr_access_scope is :admin,
+# :rest_api or :fhir):
+# OpenehrRails.authenticate_with = lambda do
+#   openehr_access_scope == :admin ? authenticate_user! : authenticate_or_request_with_http_token { |t, _| valid_api_token?(t) }
+# end
+#
+# Explicit opt-out for intentionally-open deployments (e.g. behind a
+# reverse proxy that already authenticates, network-isolated internal
+# apps) -- NOT recommended for anything reachable outside your network:
+# OpenehrRails.allow_unauthenticated_access = true

data/lib/openehr-rails/version.rb

@@ -1,5 +1,5 @@
 module OpenEHR
   module Rails
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/openehr_rails/opt/remote_fetcher.rb

@@ -2,6 +2,8 @@
 
 require 'net/http'
 require 'uri'
+require 'ipaddr'
+require 'resolv'
 require 'openehr_rails/opt'
 
 module OpenehrRails
@@ -20,6 +22,21 @@ module OpenehrRails
       READ_TIMEOUT = 20
       ALLOWED_SCHEMES = %w[http https].freeze
 
+      # Loopback, private, and link-local ranges (the latter includes the
+      # 169.254.169.254 cloud-metadata endpoint AWS/GCP/Azure all use).
+      # Checked against every hop (initial URL and every redirect target,
+      # since parse_uri runs on each via #get), not just the first.
+      BLOCKED_IP_RANGES = [
+        IPAddr.new('127.0.0.0/8'),
+        IPAddr.new('10.0.0.0/8'),
+        IPAddr.new('172.16.0.0/12'),
+        IPAddr.new('192.168.0.0/16'),
+        IPAddr.new('169.254.0.0/16'),
+        IPAddr.new('::1/128'),
+        IPAddr.new('fc00::/7'),
+        IPAddr.new('fe80::/10')
+      ].freeze
+
       def self.fetch(url)
         new(url).fetch
       end
@@ -58,10 +75,30 @@ module OpenehrRails
         unless ALLOWED_SCHEMES.include?(uri.scheme)
           raise FetchError, "unsupported URL scheme: #{uri.scheme.inspect} (must be http/https)"
         end
+        if blocked_host?(uri.host)
+          raise FetchError, "refusing to fetch #{url}: host resolves to a private/internal/link-local address"
+        end
 
         uri
       end
 
+      # True if `host` (a literal IP, a bracketed IPv6 literal, or a
+      # hostname to resolve) is, or resolves to, a loopback/private/
+      # link-local address. Fails open on an unresolvable hostname --
+      # Net::HTTP will then fail on its own DNS lookup, converted to a
+      # FetchError by #get's rescue clause.
+      def blocked_host?(host)
+        literal = literal_ip(host)
+        addresses = literal ? [literal] : Resolv.getaddresses(host).filter_map { |ip| literal_ip(ip) }
+        addresses.any? { |address| BLOCKED_IP_RANGES.any? { |range| range.include?(address) } }
+      end
+
+      def literal_ip(host)
+        IPAddr.new(host)
+      rescue IPAddr::Error
+        nil
+      end
+
       def request(uri)
         Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
                                             open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|

data/lib/openehr_rails.rb

@@ -63,4 +63,29 @@ module OpenehrRails
 
     defined?(::Rails.env) && ::Rails.env.development?
   end
+
+  # Authentication hook, run via before_action ahead of every engine
+  # action (all controllers inherit from OpenehrRails::ApplicationController).
+  # A zero-arity proc, instance_exec'd in the controller -- so it can use
+  # request/render/redirect_to/head and any helper the host mixes into
+  # ActionController::Base (e.g. Devise's authenticate_user!). Deny by
+  # rendering or redirecting (standard before_action halting); some engine
+  # controllers rescue_from StandardError, so a hook that raises instead
+  # of rendering would be masked as a misleading error response --
+  # render/redirect only.
+  mattr_accessor :authenticate_with, default: nil
+
+  # Explicit escape hatch for intentionally-open deployments (e.g. behind
+  # a reverse proxy that already authenticates, or network-isolated
+  # internal-only apps). Overrides the environment-based default in
+  # EITHER direction: true forces access even in production; false forces
+  # denial even in development.
+  mattr_accessor :allow_unauthenticated_access, default: nil
+
+  def self.unauthenticated_access_allowed?
+    return allow_unauthenticated_access unless allow_unauthenticated_access.nil?
+    return false unless defined?(::Rails.env)
+
+    ::Rails.env.development? || ::Rails.env.test?
+  end
 end

data/spec/generators/openehr/install/install_generator_spec.rb

@@ -40,6 +40,8 @@ describe Openehr::Generators::InstallGenerator do
       .to contain("require 'openehr_rails'")
     expect(file('config/initializers/openehr.rb'))
       .to contain('rm_persistence_enabled')
+    expect(file('config/initializers/openehr.rb'))
+      .to contain('OpenehrRails.authenticate_with')
   end
 
   it 'creates the operational template directory' do

data/spec/openehr_rails/authentication_spec.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'openehr_rails'
+require_relative '../../app/controllers/openehr_rails/application_controller'
+
+describe 'OpenehrRails engine authentication' do
+  after do
+    OpenehrRails.authenticate_with = nil
+    OpenehrRails.allow_unauthenticated_access = nil
+  end
+
+  describe '.unauthenticated_access_allowed?' do
+    def stub_env(name)
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new(name))
+    end
+
+    it 'is true in development when unconfigured' do
+      stub_env('development')
+      expect(OpenehrRails.unauthenticated_access_allowed?).to be true
+    end
+
+    it 'is true in test when unconfigured' do
+      stub_env('test')
+      expect(OpenehrRails.unauthenticated_access_allowed?).to be true
+    end
+
+    it 'is false in production when unconfigured' do
+      stub_env('production')
+      expect(OpenehrRails.unauthenticated_access_allowed?).to be false
+    end
+
+    it 'honours an explicit true override even in production' do
+      stub_env('production')
+      OpenehrRails.allow_unauthenticated_access = true
+      expect(OpenehrRails.unauthenticated_access_allowed?).to be true
+    end
+
+    it 'honours an explicit false override even in development' do
+      stub_env('development')
+      OpenehrRails.allow_unauthenticated_access = false
+      expect(OpenehrRails.unauthenticated_access_allowed?).to be false
+    end
+  end
+
+  describe OpenehrRails::ApplicationController do
+    subject(:controller) { described_class.new }
+
+    def stub_request(json: true)
+      allow(controller).to receive(:request).and_return(
+        instance_double(ActionDispatch::Request, format: double('format', json?: json))
+      )
+    end
+
+    before do
+      allow(controller).to receive(:render)
+      stub_request
+    end
+
+    it 'defaults openehr_access_scope to :admin' do
+      expect(controller.openehr_access_scope).to eq(:admin)
+    end
+
+    context 'when no hook is configured' do
+      it 'allows the request in development/test (unauthenticated_access_allowed? true)' do
+        allow(OpenehrRails).to receive(:unauthenticated_access_allowed?).and_return(true)
+
+        controller.send(:authenticate_openehr_access!)
+
+        expect(controller).not_to have_received(:render)
+      end
+
+      it 'denies the request with 403 JSON outside development/test' do
+        allow(OpenehrRails).to receive(:unauthenticated_access_allowed?).and_return(false)
+        stub_request(json: true)
+
+        controller.send(:authenticate_openehr_access!)
+
+        expect(controller).to have_received(:render).with(hash_including(status: :forbidden, json: anything))
+      end
+
+      it 'denies non-JSON requests with a plain-text 403' do
+        allow(OpenehrRails).to receive(:unauthenticated_access_allowed?).and_return(false)
+        stub_request(json: false)
+
+        controller.send(:authenticate_openehr_access!)
+
+        expect(controller).to have_received(:render).with(hash_including(status: :forbidden, plain: anything))
+      end
+    end
+
+    context 'when a hook is configured' do
+      it 'defers entirely to the hook, even outside development/test' do
+        allow(OpenehrRails).to receive(:unauthenticated_access_allowed?).and_return(false)
+        ran = false
+        OpenehrRails.authenticate_with = -> { ran = true }
+
+        controller.send(:authenticate_openehr_access!)
+
+        expect(ran).to be true
+        expect(controller).not_to have_received(:render)
+      end
+
+      it 'instance_execs the hook in controller context so it can call controller methods' do
+        def controller.custom_auth_check
+          render plain: 'nope', status: :unauthorized
+        end
+        OpenehrRails.authenticate_with = -> { custom_auth_check }
+
+        controller.send(:authenticate_openehr_access!)
+
+        expect(controller).to have_received(:render).with(hash_including(status: :unauthorized))
+      end
+    end
+  end
+
+  describe 'openehr_access_scope overrides' do
+    require_relative '../../app/controllers/openehr_rails/fhir_controller'
+    require_relative '../../app/controllers/openehr_rails/queries_controller'
+    require_relative '../../app/controllers/openehr_rails/openehr_api/ehrs_controller'
+    require_relative '../../app/controllers/openehr_rails/openehr_api/compositions_controller'
+
+    it 'is :fhir for FhirController' do
+      expect(OpenehrRails::FhirController.new.openehr_access_scope).to eq(:fhir)
+    end
+
+    it 'is :rest_api for OpenehrApi::EhrsController and OpenehrApi::CompositionsController' do
+      expect(OpenehrRails::OpenehrApi::EhrsController.new.openehr_access_scope).to eq(:rest_api)
+      expect(OpenehrRails::OpenehrApi::CompositionsController.new.openehr_access_scope).to eq(:rest_api)
+    end
+
+    it 'is :rest_api for QueriesController#execute and :admin for QueriesController#show' do
+      controller = OpenehrRails::QueriesController.new
+      allow(controller).to receive(:action_name).and_return('execute')
+      expect(controller.openehr_access_scope).to eq(:rest_api)
+
+      allow(controller).to receive(:action_name).and_return('show')
+      expect(controller.openehr_access_scope).to eq(:admin)
+    end
+  end
+end

data/spec/openehr_rails/opt/remote_fetcher_spec.rb

@@ -68,4 +68,39 @@ describe OpenehrRails::Opt::RemoteFetcher do
     expect { described_class.fetch('https://example.com/slow.opt') }
       .to raise_error(described_class::FetchError)
   end
+
+  describe 'SSRF protection' do
+    # No stub_request for any of these: a correctly-blocked URL must never
+    # reach Net::HTTP at all (WebMock would raise its own "real requests
+    # are not allowed" error if it did, which -- being a different error
+    # class -- would also fail these expectations).
+    [
+      '127.0.0.1',        # loopback
+      '169.254.169.254',  # link-local, incl. cloud metadata endpoints
+      '10.1.2.3',         # private
+      '172.16.0.5',       # private
+      '192.168.1.1',      # private
+      '[::1]' # IPv6 loopback
+    ].each do |host|
+      it "rejects a URL targeting the blocked address #{host}" do
+        expect { described_class.fetch("http://#{host}/x.opt") }
+          .to raise_error(described_class::FetchError, /internal|private|blocked/i)
+      end
+    end
+
+    it 'rejects a redirect to a blocked address, not just the initial URL' do
+      stub_request(:get, 'https://example.com/external.opt')
+        .to_return(status: 302, headers: { 'Location' => 'http://127.0.0.1/internal.opt' })
+
+      expect { described_class.fetch('https://example.com/external.opt') }
+        .to raise_error(described_class::FetchError, /internal|private|blocked/i)
+    end
+
+    it 'still allows a normal public host' do
+      stub_request(:get, 'https://example.com/bmi_calculation.opt')
+        .to_return(status: 200, body: opt_body)
+
+      expect(described_class.fetch('https://example.com/bmi_calculation.opt')).to eq(opt_body)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openehr-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Shinji KOBAYASHI
@@ -310,6 +310,7 @@ files:
 - spec/openehr_rails/aql/executor_spec.rb
 - spec/openehr_rails/aql/model_api_spec.rb
 - spec/openehr_rails/aql/query_validator_spec.rb
+- spec/openehr_rails/authentication_spec.rb
 - spec/openehr_rails/fhir/profile_generator_spec.rb
 - spec/openehr_rails/fhir/serializer_spec.rb
 - spec/openehr_rails/naming_spec.rb