woods 1.2.0 → 1.3.0

data/lib/woods/model_name_cache.rb

@@ -7,12 +7,25 @@ module Woods
   # Avoids O(n*m) per-extractor iteration of ActiveRecord::Base.descendants.
   # Invalidated per extraction run (call .reset! before a new run).
   #
+  # Provides two resolution layers:
+  # 1. {.model_names_regex} — whole-word match against every fully-qualified
+  #    model name. Catches `User`, `Library::Book`, and `"Library::Book"`
+  #    (as a string literal) because `\b` treats `:` and `"` as boundaries.
+  # 2. {.resolve_short_name} — when source references the bare inner name
+  #    (e.g. `Book.new` inside `module Library`), resolve it back to its
+  #    fully-qualified owner when the short name is unambiguous. Needed
+  #    because the cache holds `Library::Book` but the source writes
+  #    `Book` after a `module Library` opens.
+  #
   # @example
   #   Woods::ModelNameCache.model_names
-  #   # => ["User", "Order", "Product", ...]
+  #   # => ["User", "Library::Book", ...]
   #
   #   Woods::ModelNameCache.model_names_regex
-  #   # => /\b(?:User|Order|Product|...)\b/
+  #   # => /\b(?:User|Library::Book|...)\b/
+  #
+  #   Woods::ModelNameCache.resolve_short_name("Book")
+  #   # => "Library::Book"   (or nil when ambiguous)
   #
   module ModelNameCache
     class << self
@@ -26,10 +39,40 @@ module Woods
         @model_names_regex ||= build_regex
       end
 
+      # Short-name → fully-qualified owner mapping. Ambiguous short names
+      # (two different models sharing the same inner name) map to nil so
+      # callers can detect the collision and skip the edge rather than
+      # guess.
+      #
+      # @return [Hash{String => String, nil}]
+      def short_name_map
+        @short_name_map ||= build_short_name_map
+      end
+
+      # Resolve a bare short name (e.g. `Book`) to its fully-qualified
+      # owner (`Library::Book`) when unambiguous. Returns nil otherwise.
+      #
+      # @param short [String]
+      # @return [String, nil]
+      def resolve_short_name(short)
+        short_name_map[short.to_s]
+      end
+
+      # Regex matching bare short names of namespaced models. Used by the
+      # dependency scanner to surface references like `Book.new`
+      # inside the `Library` module, which the full-name regex misses.
+      #
+      # @return [Regexp]
+      def short_names_regex
+        @short_names_regex ||= build_short_names_regex
+      end
+
       # Clear cache (call at the start of each extraction run)
       def reset!
         @model_names = nil
         @model_names_regex = nil
+        @short_name_map = nil
+        @short_names_regex = nil
       end
 
       private
@@ -46,6 +89,39 @@ module Woods
 
         /\b(?:#{names.map { |n| Regexp.escape(n) }.join('|')})\b/
       end
+
+      # Build short-name → full-name mapping. A short name that appears on
+      # multiple fully-qualified models resolves to nil so ambiguity bubbles
+      # up (instead of silently picking one). Bare top-level names
+      # (no `::`) map to themselves.
+      def build_short_name_map
+        map = {}
+        model_names.each do |full|
+          short = full.split('::').last
+          map[short] = if map.key?(short) && map[short] != full
+                         nil # mark ambiguous
+                       else
+                         full
+                       end
+        end
+        map
+      end
+
+      def build_short_names_regex
+        unambiguous = short_name_map.select { |short, full| full && short != full }.keys
+        return /(?!)/ if unambiguous.empty?
+
+        # Match the short name only when:
+        # - NOT preceded by `::`, `.`, or another word char (avoids
+        #   double-counting the full-name hit + rejects `RareBook`).
+        # - Followed by a recognisable constant-use context: method call
+        #   (`.` / `(`), namespace (`::`), list boundary (`,` / `)` / `]`),
+        #   or end-of-line. This filters out mentions inside sentences
+        #   (" ... update Book later") and inside string literals
+        #   that lack a follow-up method call (`"Book"` alone).
+        names = unambiguous.map { |n| Regexp.escape(n) }.join('|')
+        /(?<![:.\w])(?:#{names})\b(?=\s*(?:\.|::|\(|,|\)|\]|=(?!=)|$))/
+      end
     end
   end
 end

data/lib/woods/notion/client.rb

@@ -146,6 +146,11 @@ module Woods
 
       # Execute HTTP with rate limiting and network error retry.
       #
+      # Any message from an underlying network error is run through
+      # {#redact_token} before being re-raised — a malformed reflected
+      # URL or request dump from the stdlib must not leak the bearer
+      # token into logs or backtraces.
+      #
       # @return [Net::HTTPResponse]
       # @raise [Woods::Error] on persistent network failures
       def execute_with_retry(method, path, body)
@@ -154,7 +159,10 @@ module Woods
           @rate_limiter.throttle { execute_http(method, path, body) }
         rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED => e
           attempts += 1
-          raise Woods::Error, "Network error after #{attempts} retries: #{e.message}" if attempts >= MAX_RETRIES
+          if attempts >= MAX_RETRIES
+            raise Woods::Error,
+                  "Network error after #{attempts} retries: #{redact_token(e.message)}"
+          end
 
           sleep(2**attempts)
           retry
@@ -162,6 +170,9 @@ module Woods
       end
 
       # Raise a descriptive error from a non-success Notion response.
+      # The response body is scrubbed before being formatted into the
+      # exception — if the Notion API ever echoes back a header (or a
+      # proxy does), the bearer token must not surface here.
       #
       # @raise [Woods::Error]
       def raise_api_error(response)
@@ -171,7 +182,19 @@ module Woods
           { 'message' => "Unparseable response body: #{response.body&.slice(0, 200)}" }
         end
         message = parsed['message'] || 'Unknown error'
-        raise Woods::Error, "Notion API error #{response.code}: #{message}"
+        raise Woods::Error,
+              "Notion API error #{response.code}: #{redact_token(message)}"
+      end
+
+      # Replace every occurrence of the bearer token with `[REDACTED]`.
+      # Defense in depth — no exception message emitted by this client
+      # should carry the secret even if a future code path embeds the
+      # request headers verbatim.
+      def redact_token(message)
+        return message if message.nil? || message.empty?
+        return message if @api_token.nil? || @api_token.empty?
+
+        message.to_s.gsub(@api_token, '[REDACTED]')
       end
 
       # Perform the raw HTTP request.

data/lib/woods/notion/mappers/model_mapper.rb

@@ -15,7 +15,7 @@ module Woods
       #   properties = mapper.map(unit_data)
       #   client.create_page(database_id: db_id, properties: properties)
       #
-      class ModelMapper
+      class ModelMapper # rubocop:disable Metrics/ClassLength
         include Shared
 
         # Map a model unit to Notion Data Models page properties.
@@ -66,6 +66,16 @@ module Woods
           metadata['column_count'] || (metadata['columns'] || []).size
         end
 
+        # Extract the leading comment block from a model file, redacting
+        # any credential-shaped content before shipping it to Notion.
+        #
+        # Model header comments occasionally contain sample API keys,
+        # integration URLs with embedded passwords, or TODO references to
+        # internal secrets. Without redaction those land verbatim in a
+        # third-party SaaS database. This uses the same {CredentialScanner}
+        # that protects the Console MCP so Notion export inherits the same
+        # defenses.
+        #
         # @return [String]
         def extract_description(source_code)
           return '' unless source_code
@@ -80,7 +90,31 @@ module Woods
             end
           end
 
-          comment_lines.any? ? comment_lines.join(' ').strip : ''
+          return '' if comment_lines.empty?
+
+          raw = comment_lines.join(' ').strip
+          redact_credentials(raw)
+        end
+
+        def redact_credentials(text)
+          return text if text.empty?
+
+          # CredentialScanner#scan returns `[redacted_value, match_counts]`.
+          # Unpack the tuple — returning the whole Array would serialize to
+          # Notion as a stringified `["text...", {}]` blob.
+          redacted, _counts = scanner.scan(text)
+          redacted
+        rescue StandardError
+          # Scanner construction or scan failure — fail closed: return an
+          # empty description rather than risk leaking anything.
+          ''
+        end
+
+        def scanner
+          @scanner ||= begin
+            require 'woods/console/credential_scanner'
+            Woods::Console::CredentialScanner.new
+          end
         end
 
         # @return [String]

data/lib/woods/railtie.rb

@@ -11,28 +11,68 @@ module Woods
 
     initializer 'woods.session_tracer' do |app|
       config = Woods.configuration
-      if config.session_tracer_enabled
-        require 'woods/session_tracer/middleware'
-
-        app.middleware.use(
-          Woods::SessionTracer::Middleware,
-          store: config.session_store,
-          session_id_proc: config.session_id_proc,
-          exclude_paths: config.session_exclude_paths
-        )
+      next unless config.session_tracer_enabled
+
+      if defined?(Rails) && Rails.env.production? && !config.session_tracer_allow_production
+        msg = '[Woods] session tracer disabled in production; ' \
+              'set `session_tracer_allow_production = true` to opt in.'
+        if defined?(Rails.logger) && Rails.logger
+          Rails.logger.warn(msg)
+        else
+          warn msg
+        end
+        next
       end
+
+      require 'woods/session_tracer/middleware'
+
+      app.middleware.use(
+        Woods::SessionTracer::Middleware,
+        store: config.session_store,
+        session_id_proc: config.session_id_proc,
+        exclude_paths: config.session_exclude_paths
+      )
     end
 
     initializer 'woods.console_mcp' do |app|
       config = Woods.configuration
-      if config.console_mcp_enabled
-        require 'woods/console/rack_middleware'
+      next unless config.console_mcp_enabled
+
+      require 'woods/console/rack_middleware'
+      require 'woods/mcp/bearer_auth'
+      require 'woods/mcp/origin_guard'
 
-        app.middleware.use(
-          Woods::Console::RackMiddleware,
-          path: config.console_mcp_path
-        )
+      token = config.console_mcp_token
+      production = defined?(Rails) && Rails.env.production?
+      token_missing = token.nil? || token.to_s.empty?
+
+      if token_missing
+        msg = '[Woods Console] console_mcp_token is not set — Console MCP is a high-privilege ' \
+              'endpoint that runs SQL and model introspection against the live database. ' \
+              'Set Woods.configuration.console_mcp_token (or WOODS_CONSOLE_MCP_TOKEN env var) ' \
+              'to a 32+ character random string.'
+        raise Woods::ConfigurationError, msg if production
+
+        # Non-prod without a token: refuse to wire the middleware at all.
+        # Earlier iterations fell through and installed the RackMiddleware
+        # with ZERO auth/origin guard in front of it — a binding on 0.0.0.0
+        # (common in devcontainers/docker-compose) would expose an
+        # unauthenticated SQL-bearing endpoint to every local process.
+        # Fail-closed: warn and skip.
+        warn "#{msg} Refusing to mount the Console MCP middleware until a token is configured."
+        next
       end
+
+      # Origin guard first — rejects cross-origin POSTs before any auth cost.
+      # BearerAuth next — requires `Authorization: Bearer <token>` on every request.
+      app.middleware.use(Woods::MCP::OriginGuard, allowed_origins: Array(config.console_mcp_allowed_origins))
+      app.middleware.use(Woods::MCP::BearerAuth, token: token)
+
+      app.middleware.use(
+        Woods::Console::RackMiddleware,
+        path: config.console_mcp_path,
+        embedded_read_tools: config.console_embedded_read_tools
+      )
     end
   end
 end

data/lib/woods/resilience/circuit_breaker.rb

@@ -56,7 +56,7 @@ module Woods
         @mutex.synchronize do
           case @state
           when :open
-            unless Time.now - @last_failure_time >= @reset_timeout
+            unless monotonic_now - @last_failure_time >= @reset_timeout
               raise CircuitOpenError, "Circuit breaker is open (#{@failure_count} failures)"
             end
 
@@ -81,10 +81,17 @@ module Woods
 
       private
 
+      # Monotonic clock reading — immune to NTP slews and DST adjustments.
+      #
+      # @return [Float] seconds from an unspecified epoch.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       # Record a failure and potentially open the circuit.
       def record_failure
         @failure_count += 1
-        @last_failure_time = Time.now
+        @last_failure_time = monotonic_now
         @state = :open if @failure_count >= @threshold
       end
 

data/lib/woods/resilience/retryable_provider.rb

@@ -69,29 +69,66 @@ module Woods
         @provider.model_name
       end
 
+      # Delegate the per-provider input cap. The retry wrapper does not
+      # change the provider's budget, so just hand through whatever the
+      # inner provider reports. Without this, `respond_to?` returns true
+      # via Interface but the call raises NotImplementedError.
+      #
+      # @return [Integer, nil]
+      def max_input_tokens
+        return @provider.max_input_tokens if @provider.respond_to?(:max_input_tokens)
+
+        nil
+      end
+
+      # Maximum backoff delay in seconds. Without a cap, attempts 8+ sleep
+      # longer than most service-level timeouts (>25s) and compound retry
+      # storms across correlated workers.
+      MAX_BACKOFF_SECONDS = 30.0
+
+      # Base multiplier for exponential backoff. Delay is roughly
+      # `BACKOFF_BASE * 2**attempt` with full jitter applied on top.
+      BACKOFF_BASE = 0.1
+
       private
 
-      # Execute a block with retry logic and exponential backoff.
+      # Execute a block with retry logic, exponential backoff, and jitter.
+      #
+      # Argument errors surface immediately (non-retryable — they indicate
+      # a programming mistake or invalid input, not a transient failure).
       #
       # @yield The block to execute
       # @return [Object] The return value of the block
       # @raise [CircuitOpenError] immediately without retrying
+      # @raise [ArgumentError] immediately without retrying
       # @raise [StandardError] the last error if all retries are exhausted
       def with_retries
         attempt = 0
         begin
           attempt += 1
           yield
-        rescue CircuitOpenError
+        rescue CircuitOpenError, ArgumentError
           raise
         rescue StandardError => e
           raise e if attempt > @max_retries
 
-          sleep((2**attempt) * 0.1)
+          sleep(backoff_seconds(attempt))
           retry
         end
       end
 
+      # Full-jitter exponential backoff with a hard cap. See "Exponential
+      # Backoff and Jitter", AWS Architecture Blog (Marc Brooker, 2015):
+      # a uniformly random delay in [0, base*2**attempt] de-correlates
+      # competing retry waves.
+      #
+      # @param attempt [Integer] 1-based attempt counter
+      # @return [Float] seconds to sleep before the next retry
+      def backoff_seconds(attempt)
+        ceiling = [BACKOFF_BASE * (2**attempt), MAX_BACKOFF_SECONDS].min
+        rand * ceiling
+      end
+
       # Route a call through the circuit breaker if one is configured.
       #
       # @yield The block to execute