monkrb 0.15.0

data/lib/monk/auth.rb

@@ -0,0 +1,301 @@
+require "securerandom"
+require "digest"
+require "openssl"
+
+require_relative "freeze_hooks"
+require_relative "auth/errors"
+require_relative "auth/login_token"
+require_relative "auth/session"
+require_relative "auth/helpers"
+require_relative "auth/rate_limiter"
+
+module Monk
+  # Passwordless token auth. Opt-in: require "monk/auth" explicitly --
+  # `require "monk"` alone does not load this, since it depends on a
+  # persistence backend the app may not use (docs/design/auth-sessions.md).
+  module Auth
+    REQUIRED_CONFIG_KEYS = %i[db_name secret login_ttl session_ttl].freeze
+
+    class << self
+      # Called from Base#freeze! (Seam B), via Monk.freeze_hooks. Freezes
+      # the value, not the module -- Monk::Auth is always Ractor.shareable?
+      # regardless of its ivars, so freezing the module itself would do
+      # nothing (docs/design/persistence-ractor-connections.md "Phase 4/5 finding").
+      def freeze_registry!
+        begin
+          @config = Ractor.make_shareable(@config)
+        rescue ArgumentError, Ractor::IsolationError => e
+          raise Monk::UnshareableBlockError,
+            "Monk::Auth.configure(deliver:) is not Ractor-shareable: #{e.message} " \
+            "(build it where self is shareable, e.g. as a module constant at class/module-body " \
+            "scope -- self at a script's top level, e.g. config/auth.rb itself, is not shareable, " \
+            "same constraint as Monk::Live.authorize blocks)"
+        end
+        freeze_rqrcode!
+      end
+
+      def configure(
+        db_name: nil, secret: nil, login_ttl: nil, session_ttl: nil, redirect_allowlist: [], secure: true,
+        deliver: nil
+      )
+        config = {
+          db_name: db_name, secret: secret, login_ttl: login_ttl, session_ttl: session_ttl,
+          redirect_allowlist: redirect_allowlist, secure: secure, deliver: deliver,
+        }
+
+        REQUIRED_CONFIG_KEYS.each do |key|
+          raise Monk::MissingAuthConfigError,
+            "Monk::Auth.configure is missing required key #{key.inspect}" if config[key].nil?
+        end
+
+        LoginToken.db_name = db_name
+        Session.db_name = db_name
+
+        @config = config
+      end
+
+      def config
+        @config
+      end
+
+      # Test-only: drops the current config. Not part of the app-facing API.
+      def reset!
+        @config = nil
+      end
+
+      def request_login(email, redirect_to: nil)
+        ensure_configured!
+        if redirect_to && !config[:redirect_allowlist].include?(redirect_to)
+          raise Monk::InvalidRedirectError, "#{redirect_to.inspect} is not in Monk::Auth's redirect_allowlist"
+        end
+
+        raw = SecureRandom.urlsafe_base64(32)
+
+        LoginToken.create(
+          email: email,
+          token_hash: hash_token(raw),
+          redirect_to: redirect_to,
+          expires_at: Time.now + config[:login_ttl],
+        )
+
+        raw
+      end
+
+      # The single place an app's login-request handler calls to get a
+      # magic link to its owner: uses the `deliver:` callable passed to
+      # `configure` (e.g. wrapping a mailer or a provider's HTTP API) when
+      # one is set, regardless of environment -- an app that wants to
+      # exercise real delivery in development is free to. With no
+      # `deliver:` configured, falls back to #log_dev_link in development
+      # (see below), and raises everywhere else: a silent no-op here would
+      # mean an app that forgot to wire delivery finds out only when a
+      # user reports never receiving their link, in production, which is
+      # the wrong place to fail (docs/design/auth-sessions.md's "Email
+      # delivery stays outside the framework" -- Monk still needs to know
+      # it was told to send *something*).
+      #
+      # `link` is the app's own job to build (Monk doesn't own routing, so
+      # it can't know the callback path) -- from a trusted origin, e.g.
+      # Monk::Settings[:public_url], never from request headers like
+      # X-Forwarded-Proto/Host, which any direct client can spoof.
+      # `token` is passed through for a deliver: that wants it (an SMS
+      # body instead of a link, say); most won't need it.
+      def deliver_link(email:, link:, token: nil)
+        ensure_configured!
+
+        if config[:deliver]
+          config[:deliver].call(email: email, link: link, token: token)
+        elsif Monk.env.development?
+          log_dev_link(link, subject: email)
+        else
+          raise MissingAuthDeliveryError,
+            "Monk::Auth.configure(deliver:) is not set, and this isn't development -- " \
+            "#{email.inspect}'s magic link would never be sent. Configure a deliver: " \
+            "callable (wrapping your mailer or provider's API), or call " \
+            "Monk::Auth.log_dev_link directly if that's truly intended here."
+        end
+      end
+
+      # Convenience for an app's own login-request handler: prints a
+      # magic link to the dev console (and log/development.log via
+      # Monk::Log.info), plus a scannable QR code beneath it if the
+      # optional `rqrcode` gem is in the app's own Gemfile -- makes
+      # testing the login flow from a second device (another browser, a
+      # phone) trivial without a mailer. A no-op outside development,
+      # same posture as every other dev-only escape hatch in this
+      # framework (docs/history/secure-cookie-dev-http.md). #deliver_link
+      # above is what an app should call day to day; this is its
+      # development-only fallback and is still fine to call directly.
+      #
+      # subject: is optional context for the printed line only (e.g. the
+      # email being logged in) -- useful once more than one login is in
+      # flight at a time (two test users, two devices), never persisted
+      # or otherwise part of the token itself.
+      #
+      # rqrcode is opt-in, same as pg/redis: not a runtime dependency of
+      # monk itself (see monk.gemspec) -- an app that wants the QR code
+      # declares it in its own Gemfile. Without it, this still logs the
+      # plain link, just no QR beneath it.
+      def log_dev_link(link, subject: nil)
+        return unless Monk.env.development?
+
+        line = subject ? "[dev] magic link for #{subject}: #{link}" : "[dev] magic link: #{link}"
+        $stdout.puts(line)
+        $stdout.flush
+        Monk::Log.info(line)
+
+        begin
+          require "rqrcode"
+        rescue LoadError
+          return
+        end
+
+        $stdout.puts(compact_qr(RQRCode::QRCode.new(link, level: :l)))
+      end
+
+      def redeem(raw)
+        ensure_configured!
+        return nil if raw.nil? || raw.empty?
+
+        row = LoginToken.where(token_hash: hash_token(raw)).first
+        return nil unless row
+        return nil if row[:expires_at] <= Time.now
+
+        claimed = LoginToken.claim({ id: row[:id], used_at: nil }, used_at: Time.now)
+        return nil unless claimed
+
+        session_raw = SecureRandom.urlsafe_base64(32)
+        expires_at = Time.now + config[:session_ttl]
+        Session.create(subject: row[:email], token_hash: hash_token(session_raw), expires_at: expires_at)
+
+        { token: session_raw, subject: row[:email], expires_at: expires_at, redirect_to: row[:redirect_to] }
+      end
+
+      def verify(raw)
+        ensure_configured!
+        return nil if raw.nil? || raw.empty?
+
+        row = Session.where(token_hash: hash_token(raw)).first
+        return nil unless row
+        return nil if row[:revoked_at]
+        return nil if row[:expires_at] <= Time.now
+
+        row[:subject]
+      end
+
+      def revoke(raw)
+        ensure_configured!
+        row = Session.where(token_hash: hash_token(raw)).first
+        return false unless row
+
+        Session.update(row[:id], revoked_at: Time.now)
+        true
+      end
+
+      def revoke_all(subject)
+        ensure_configured!
+        rows = Session.where(subject: subject).select { |row| row[:revoked_at].nil? }
+        now = Time.now
+        rows.each { |row| Session.update(row[:id], revoked_at: now) }
+        rows.size
+      end
+
+      # Deliberately not grown onto Model: a `<` comparison is real
+      # query-DSL scope for a hygiene task (docs/design/auth-sessions.md).
+      def sweep!
+        ensure_configured!
+        Monk::Persistence::Pg.checkout(config[:db_name]) do |conn|
+          now = Time.now
+          login_tokens_deleted = conn.exec_params("DELETE FROM login_tokens WHERE expires_at < $1", [now]).cmd_tuples
+          sessions_deleted = conn.exec_params("DELETE FROM sessions WHERE expires_at < $1", [now]).cmd_tuples
+          { login_tokens: login_tokens_deleted, sessions: sessions_deleted }
+        end
+      end
+
+      # Stateless double-submit CSRF token, derived not stored
+      # (docs/design/auth-sessions.md's "CSRF: stateless double-submit, no third
+      # table") -- the one HMAC implementation set_session_cookie and
+      # require_csrf! both call, so there's no second place this could
+      # drift out of sync.
+      def csrf_token_for(session_token)
+        OpenSSL::HMAC.hexdigest("SHA256", config[:secret], session_token)
+      end
+
+      private
+
+      # as_ansi spends two columns and one line per module, so even a
+      # short link fills the terminal. Half-block characters pack two
+      # module rows into one line and one column per module (roughly a
+      # quarter of the area); the explicit black-on-white colors keep it
+      # scannable on dark terminals too. Quiet zone is 2 modules, below
+      # the spec's 4 but reliable for phone cameras against a white
+      # background.
+      def compact_qr(qr, quiet_zone: 2)
+        width = qr.modules.size + quiet_zone * 2
+        blank = Array.new(quiet_zone) { Array.new(width, false) }
+        grid = blank + qr.modules.map { |row| Array.new(quiet_zone, false) + row + Array.new(quiet_zone, false) } + blank
+        grid << Array.new(width, false) if grid.size.odd?
+
+        grid.each_slice(2).map do |top, bottom|
+          cells = top.zip(bottom).map do |t, b|
+            if t && b then "\u2588"
+            elsif t then "\u2580"
+            elsif b then "\u2584"
+            else " "
+            end
+          end
+          # dark modules are the glyph (black fg) on a white bg
+          "\e[30;47m#{cells.join}\e[0m"
+        end.join("\n")
+      end
+
+      def ensure_configured!
+        raise Monk::AuthNotConfiguredError,
+          "Monk::Auth is not configured -- call Monk::Auth.configure first" unless @config
+      end
+
+      def hash_token(raw)
+        Digest::SHA256.hexdigest(raw)
+      end
+
+      # rqrcode (used by log_dev_link) is a third-party gem with no
+      # Ractor awareness of its own: several of its lookup tables
+      # (RQRCodeCore::QRUtil::PATTERN_POSITION_TABLE and siblings) are
+      # ordinary, unfrozen constants. Reading one of those from a worker
+      # Ractor -- which is exactly what happens the first time
+      # log_dev_link runs inside a real request under Kino -- raises
+      # Ractor::IsolationError regardless of which Ractor originally
+      # required the gem; only the object's own shareability matters
+      # (confirmed live: requiring rqrcode in the main Ractor first does
+      # not help). Walking its constants here, at boot in the main
+      # Ractor, and freezing each one is the same fix
+      # docs/design/persistence-ractor-connections.md documents for this exact
+      # class of problem elsewhere in the stack. A no-op if the app
+      # hasn't added rqrcode to its own Gemfile (see log_dev_link).
+      def freeze_rqrcode!
+        require "rqrcode"
+      rescue LoadError
+        nil
+      else
+        freeze_constants!(RQRCodeCore)
+        freeze_constants!(RQRCode)
+      end
+
+      def freeze_constants!(mod, seen = {}.compare_by_identity)
+        return if seen[mod]
+        seen[mod] = true
+
+        mod.constants(false).each do |name|
+          value = mod.const_get(name)
+          if value.is_a?(Module)
+            freeze_constants!(value, seen) if value.name&.start_with?("RQRCode")
+          else
+            Ractor.make_shareable(value)
+          end
+        end
+      end
+    end
+
+    Monk.freeze_hooks << self
+  end
+end

data/lib/monk/base.rb

@@ -0,0 +1,323 @@
+require "json"
+require "uri"
+
+require_relative "freeze_hooks"
+require_relative "environment"
+
+module Monk
+  class Base
+    VERBS = %w[GET POST PUT PATCH DELETE].freeze
+    private_constant :VERBS
+
+    EMPTY_ARRAY = [].freeze
+    private_constant :EMPTY_ARRAY
+
+    # Action name -> path suffix (appended to the resource path) and verb(s)
+    # it dispatches on, for #resources. :update registers both PATCH and PUT --
+    # PATCH is the canonical partial-update verb, PUT accepted too since
+    # plenty of clients only ever send it for "update this resource".
+    REST_ACTIONS = {
+      index: { verbs: %w[GET], path: "" },
+      new: { verbs: %w[GET], path: "/new" },
+      create: { verbs: %w[POST], path: "" },
+      show: { verbs: %w[GET], path: "/:id" },
+      edit: { verbs: %w[GET], path: "/:id/edit" },
+      update: { verbs: %w[PATCH PUT], path: "/:id" },
+      destroy: { verbs: %w[DELETE], path: "/:id" },
+    }.freeze
+    private_constant :REST_ACTIONS
+
+    class << self
+      VERBS.each do |verb|
+        define_method(verb.downcase) do |path, &block|
+          routes << { verb: verb, path: path, block: block }
+        end
+      end
+
+      def routes
+        @routes ||= []
+      end
+
+      # EXPERIMENTAL: this is the one place Base's routing DSL departs
+      # from "verb(path) { block }" -- a controller class plus a list of
+      # action symbols, instead of a block. Not yet convinced that's the
+      # right shape (see monk-consumer-test session notes); may be
+      # reworked or removed rather than kept as-is.
+      #
+      # Registers a conventional set of REST routes rooted at `path` (e.g.
+      # "/orders" -> "/orders", "/orders/new", "/orders/:id", ...), each
+      # dispatching to `controller.new(context).public_send(action)`.
+      # `actions` defaults to all seven (index/new/create/show/edit/
+      # update/destroy); pass a subset to only wire up what `controller`
+      # actually implements -- an action not listed here raises
+      # ArgumentError immediately, rather than registering a route to a
+      # method that doesn't exist.
+      #
+      # Built entirely on top of #get/#post/#put/#patch/#delete above --
+      # no change to routing, dispatch, or freeze!, so an app that never
+      # calls #resources is unaffected.
+      def resources(path, controller, *actions)
+        actions = REST_ACTIONS.keys if actions.empty?
+        path = path.to_s.delete_prefix("/")
+
+        actions.each do |action|
+          mapping = REST_ACTIONS.fetch(action) do
+            raise ArgumentError, "unknown REST action #{action.inspect} (known: #{REST_ACTIONS.keys.join(", ")})"
+          end
+
+          route = "/#{path}#{mapping[:path]}"
+          mapping[:verbs].each { |verb| send(verb.downcase, route) { controller.new(self).public_send(action) } }
+        end
+      end
+
+      # Where .erb templates live (default "views"), relative to the
+      # process's working directory and read at Boot.
+      def views(dir)
+        Monk::Views.root = dir
+      end
+
+      # Default layout template wrapped around every render, e.g.
+      # layout "layouts/app". Individual renders opt out with
+      # `render "x", layout: false`.
+      def layout(name)
+        Monk::Views.layout = name
+      end
+
+      # Where static files live (default "public"); `assets false`
+      # disables serving them.
+      def assets(dir)
+        Monk::Assets.root = dir
+      end
+
+      def freeze!
+        routes.each do |route|
+          begin
+            Ractor.make_shareable(route[:block])
+          rescue ArgumentError => e
+            raise UnshareableRouteError, "#{route[:verb]} #{route[:path]} is not Ractor-shareable: #{e.message}"
+          end
+        end
+
+        error_handlers.each do |matcher, block|
+          begin
+            Ractor.make_shareable(block)
+          rescue ArgumentError => e
+            raise UnshareableRouteError, "error handler for #{matcher.inspect} is not Ractor-shareable: #{e.message}"
+          end
+        end
+
+        Monk.freeze!
+
+        # Settled once here, not read from ENV per request in
+        # #log_request: ENV is main-Ractor state, so a per-request read
+        # from a worker Ractor is the same hazard Monk::Assets already
+        # guards against the same way. Gates the $stdout echo only --
+        # Monk::Log's file write is unconditional, every environment.
+        @console_logging = Monk.env.development?
+
+        index_routes!
+
+        Ractor.make_shareable(routes)
+        Ractor.make_shareable(@static_routes)
+        Ractor.make_shareable(@dynamic_routes)
+        Ractor.make_shareable(error_handlers)
+        self
+      end
+
+      def error(matcher, &block)
+        error_handlers << [matcher, block]
+      end
+
+      def error_handlers
+        @error_handlers ||= []
+      end
+
+      def call(env)
+        freeze! unless Ractor.shareable?(routes)
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        status, headers, body = dispatch(env)
+        log_request(env, status, start)
+        [status, headers, body]
+      end
+
+      private
+
+      def dispatch(env)
+        # Assets before routes, the position Rack::Static would occupy in
+        # front of the app -- so a catch-all splat route can't shadow a
+        # stylesheet. The tradeoff, worth knowing: a route can't override
+        # a path that exists as a file.
+        asset = Monk::Assets.response(env)
+        return asset if asset
+
+        route, path_params = find_route(env["REQUEST_METHOD"], env["PATH_INFO"])
+        return not_found_response(env) unless route
+
+        params = parse_params(env).merge(path_params)
+        context = Context.new(params, env)
+        catch(:monk_halt) do
+          begin
+            body = context.instance_exec(context, &route[:block])
+            [200, context.headers, [body]]
+          rescue StandardError => e
+            handler = error_handlers.find { |matcher, _| matcher.is_a?(Class) && e.is_a?(matcher) }
+            if handler
+              context.status = 500
+              body = context.instance_exec(context, &handler.last)
+              [500, context.headers, [body]]
+            else
+              [500, { "content-type" => "application/json" }, ['{"error":"Internal Server Error"}']]
+            end
+          end
+        end
+      end
+
+      def log_request(env, status, start)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+        line = "#{Monk::Log.timestamp} #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} -> #{status} (#{duration_ms}ms)"
+
+        if @console_logging
+          $stdout.puts line
+          # Each worker Ractor buffers $stdout independently; without an explicit
+          # flush, lines only surface when the process exits, not in real time.
+          $stdout.flush
+        end
+
+        Monk::Log.write("#{line}\n")
+      end
+
+      def not_found_response(env)
+        handler = error_handlers.find { |matcher, _| matcher == 404 }
+        return [404, {}, [""]] unless handler
+
+        context = Context.new({}, env, status: 404)
+        catch(:monk_halt) do
+          body = context.instance_exec(context, &handler.last)
+          [404, context.headers, [body]]
+        end
+      end
+
+      # Query string, then a JSON body on top (POST /auth/request's
+      # redirect_to; a callback token as ?token=... instead of a path
+      # segment -- docs/history/plan-auth.md Phase 9 step 29). Path segment params
+      # always win the final merge in #dispatch -- the route's own
+      # declared intent outranks anything a caller supplies.
+      def parse_params(env)
+        parse_query_string(env["QUERY_STRING"]).merge(parse_json_body(env))
+      end
+
+      # URI.decode_www_form, not Rack::Utils.parse_nested_query -- the
+      # latter memoizes an unfrozen QueryParser instance in a module ivar
+      # (Rack::Utils.default_query_parser) the moment "rack/utils" loads,
+      # in the main Ractor, and reading it back from a worker Ractor raises
+      # Ractor::IsolationError regardless of which Ractor set it. A bug in
+      # rack itself (not yet Ractor-safe), measured directly against a real
+      # worker Ractor rather than assumed -- no nested/array query syntax,
+      # consistent with Monk's minimal query surface elsewhere.
+      def parse_query_string(query_string)
+        return {} if query_string.to_s.empty?
+
+        URI.decode_www_form(query_string).each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      end
+
+      def parse_json_body(env)
+        return {} unless env["CONTENT_TYPE"].to_s.include?("application/json")
+
+        body = env["rack.input"]&.read.to_s
+        return {} if body.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Routes are static (literal path, no ":param" or trailing "*") in
+      # the overwhelming common case, so freeze! (#index_routes!) splits
+      # them into an O(1) exact-match table up front; only routes that
+      # actually need segment-by-segment matching pay for it at request
+      # time. Both structures hold the exact same route Hash objects that
+      # `routes` does, so making `routes` shareable would freeze them too
+      # -- but since they're not reachable *from* `routes`, they need
+      # their own Ractor.make_shareable call in #freeze!.
+      def index_routes!
+        static = {}
+        dynamic = {}
+        VERBS.each do |verb|
+          static[verb] = {}
+          dynamic[verb] = []
+        end
+
+        routes.each do |route|
+          segments = route[:path].split("/")
+          route[:segments] = segments
+
+          if segments.last == "*"
+            route[:prefix_segments] = segments[0...-1]
+            dynamic[route[:verb]] << route
+          elsif segments.any? { |s| s.start_with?(":") }
+            dynamic[route[:verb]] << route
+          else
+            static[route[:verb]][route[:path]] = route
+          end
+        end
+
+        @static_routes = static
+        @dynamic_routes = dynamic
+      end
+
+      def find_route(verb, path)
+        static_route = @static_routes.dig(verb, path)
+        return [static_route, {}] if static_route
+
+        path_segments = path.split("/")
+
+        (@dynamic_routes[verb] || EMPTY_ARRAY).each do |route|
+          if route[:prefix_segments]
+            prefix = route[:prefix_segments]
+            next if path_segments.size < prefix.size
+            next unless segments_match?(prefix, path_segments)
+
+            params = extract_params(prefix, path_segments)
+            params[:splat] = path_segments[prefix.size..].join("/")
+            return [route, params]
+          else
+            route_segments = route[:segments]
+            next unless route_segments.size == path_segments.size
+            next unless segments_match?(route_segments, path_segments)
+
+            return [route, extract_params(route_segments, path_segments)]
+          end
+        end
+
+        nil
+      end
+
+      # Boolean-only: whether a candidate route matches is decided before
+      # any params Hash is allocated, so a failed candidate costs nothing
+      # beyond the comparisons themselves.
+      def segments_match?(route_segments, path_segments)
+        route_segments.each_with_index.all? do |segment, i|
+          segment.start_with?(":") || segment == path_segments[i]
+        end
+      end
+
+      def extract_params(route_segments, path_segments)
+        params = {}
+        route_segments.each_with_index do |segment, i|
+          params[segment[1..].to_sym] = path_segments[i] if segment.start_with?(":")
+        end
+        params
+      end
+    end
+
+    def call(env)
+      self.class.call(env)
+    end
+
+    def freeze!
+      self.class.freeze!
+      self
+    end
+  end
+end

data/lib/monk/context.rb

@@ -0,0 +1,78 @@
+require "json"
+
+require_relative "views"
+require_relative "assets"
+
+module Monk
+  class Context
+    include Monk::Views::Compiled
+
+    attr_reader :params, :env, :headers
+    attr_accessor :status
+
+    # Internal: true while a template is rendering, so the default layout
+    # wraps the page once and not every partial it renders.
+    attr_accessor :rendering
+
+    def initialize(params, env = {}, status: 200)
+      @params = params
+      @env = env
+      @status = status
+      @headers = {}
+      @rendering = false
+    end
+
+    def header(name)
+      env["HTTP_#{name.upcase.tr("-", "_")}"]
+    end
+
+    def halt(status, body = "")
+      throw :monk_halt, [status, headers, [body]]
+    end
+
+    def redirect(location, status: 302)
+      headers["location"] = location
+      throw :monk_halt, [status, headers, [""]]
+    end
+
+    def json(data)
+      headers["content-type"] = "application/json"
+      throw :monk_halt, [status, headers, [JSON.generate(data)]]
+    end
+
+    # Renders a template and *returns* the HTML, unlike #json and #halt,
+    # which throw. That's what makes a partial work: a template rendering
+    # another template is this same call, and a route block's return value
+    # is already the response body.
+    #
+    # Data reaches a template two ways, both zero-machinery: ivars set in
+    # the route (the route block, the template and the layout all run with
+    # `self` bound to this same Context), and the `locals` hash passed
+    # here, which is what a partial rendered inside a loop wants.
+    def render(name, layout: :default, **locals)
+      headers["content-type"] ||= "text/html; charset=utf-8"
+      Monk::Views.render(self, name, locals, layout: layout)
+    end
+
+    def h(value)
+      Monk::Views.h(value)
+    end
+
+    # Marks a string as already-safe, so the implicit escaping around
+    # every `<%= %>` leaves it alone.
+    def raw(value)
+      Monk::Views::Raw.new(value.to_s)
+    end
+
+    def asset_path(path)
+      Monk::Assets.path_for(path)
+    end
+
+    # Same frozen values Monk::Settings[] reads, e.g. `settings[:api_key]`
+    # -- returns the module itself rather than duplicating its #[] here,
+    # so an undeclared key raises the exact same way through either path.
+    def settings
+      Monk::Settings
+    end
+  end
+end