hookd-client 1.2.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e020dd2f4705d56fdc57c2a7da6daba65231a9676a534037104d98cd401bcdaa
-  data.tar.gz: 505b0f7151a9b7dfc02638b7b6c5978be6ef9832987c85b2b6b27ca7262cf8d5
+  metadata.gz: 5ff2c6d9ea446cd5631e2c3f4d3f27a0586a130acaf6bf9e10f9a7fb6613efc3
+  data.tar.gz: 38021e8c18baee9ff374c60d305cc6312cf024a2fff120e926cfa89d9d44ea52
 SHA512:
-  metadata.gz: 32da3c04302a2e04ce0d1ea42b05f438d80e12fadfcae77de8720d1e5894d56ada4ab8b5db77d934b3bec64378d8140b747b761996931c39bd1f9b70656f94e9
-  data.tar.gz: 78080b0c8e32c86d7634e8d137bfa8a9471e03351a4449ec6f969f12d452ffbd912d6e9ad91ef9ce832853dcd8d3c102ad567d6d3d706e1f49349158c1ebebb4
+  metadata.gz: 3cc77be594c69256a2de2e31a23a7654dddbf94c50f0402fa327e3865e2fa25af4c4c4dfab6e9ca641aa611b20da6e22760646d570676a4a87e92d08382f3af8
+  data.tar.gz: 1d2da85d42bfff6ba7bcf2e1211b418c7bc8944ce8119169388e1b51cec085d64a54ceb4372ea5b5869714c792836cd193b1600b526c40021ead72cf8a492d28

data/README.md

@@ -1,6 +1,6 @@
 # Hookd Ruby Client
 
-Ruby client library for [Hookd](https://github.com/JoshuaMart/hookd/server), a DNS/HTTP interaction server for security testing and debugging.
+Ruby client library for [Hookd](https://github.com/JoshuaMart/hookd/server), a DNS/HTTP/SMTP interaction server for security testing and debugging.
 
 ## Installation
 
@@ -35,6 +35,7 @@ hook = client.register
 puts "DNS endpoint: #{hook.dns}"
 puts "HTTP endpoint: #{hook.http}"
 puts "HTTPS endpoint: #{hook.https}"
+puts "Mail endpoint: #{hook.smtp}" if hook.smtp
 
 # Make a request to the HTTP endpoint to simulate an interaction
 Typhoeus.get(hook.http)
@@ -46,6 +47,8 @@ interactions.each do |interaction|
     puts "DNS query: #{interaction.data}"
   elsif interaction.http?
     puts "HTTP request: #{interaction.data}"
+  elsif interaction.smtp?
+    puts "Mail from #{interaction.data['mail_from']}: #{interaction.data['subject']}"
   end
 end
 ```
@@ -95,6 +98,8 @@ results.each do |hook_id, result|
         puts "   - DNS: #{interaction.data['qname']} (#{interaction.data['qtype']})"
       elsif interaction.http?
         puts "   - HTTP: #{interaction.data['method']} #{interaction.data['path']}"
+      elsif interaction.smtp?
+        puts "   - SMTP: #{interaction.data['mail_from']} (#{interaction.data['subject']})"
       end
     end
   end
@@ -108,6 +113,10 @@ The client requires two configuration parameters:
 - `server`: The Hookd server URL (e.g., `https://hookd.example.com`)
 - `token`: Authentication token for API access
 
+An optional `max_response_bytes:` caps the response payload the client will read
+(64 MiB by default; zero or less disables it). Exceeding it raises
+`Hookd::ResponseTooLargeError`.
+
 ### API Reference
 
 #### `Hookd::Client`
@@ -116,7 +125,7 @@ Main client class for interacting with the Hookd server.
 
 ##### `#register(count: nil)`
 
-Register one or more hooks and get DNS/HTTP endpoints.
+Register one or more hooks and get their DNS, HTTP and (when the server runs a mail listener) SMTP endpoints.
 
 **Single hook (default):**
 ```ruby
@@ -130,8 +139,20 @@ hooks = client.register(count: 5)
 # => [#<Hookd::Hook id="abc123" ...>, #<Hookd::Hook id="def456" ...>, ...]
 ```
 
+**Long-lived hook (survives restarts, for stored-XSS style detection):**
+```ruby
+hook = client.register(ttl: '7d', metadata: { target: 'acme', field: 'profile.bio' })
+# => #<Hookd::Hook id="abc123" ...>
+hook.expires_at # => "2025-10-08T10:30:00Z"
+hook.metadata   # => {"target"=>"acme", "field"=>"profile.bio"}
+```
+
 Parameters:
 - `count` (Integer, optional) - Number of hooks to create (default: 1)
+- `ttl` (String, optional) - Lifetime as a Go duration (`"168h"`) or day count
+  (`"7d"`); a value above the server's ephemeral `hook_ttl` registers a durable
+  long-lived hook. Omit for an ephemeral hook.
+- `metadata` (Hash, optional) - Stored with the hook and echoed back on poll
 
 Returns:
 - `Hookd::Hook` object when `count` is 1 or not specified
@@ -143,6 +164,21 @@ Raises:
 - `Hookd::ServerError` - Server error (5xx)
 - `Hookd::ConnectionError` - Connection failed
 
+##### `#activity`
+
+List the long-lived hooks that currently have pending interactions, so you can
+discover which fired without polling each one; drain the details with `#poll`.
+
+```ruby
+client.activity.each do |a|
+  puts "#{a.hook.id} fired #{a.pending_count} time(s), meta=#{a.hook.metadata}"
+  client.poll(a.hook.id)
+end
+# => [#<Hookd::HookActivity hook=abc123 pending=3>, ...]
+```
+
+Returns: Array of `Hookd::HookActivity` (empty when none fired or long-lived is disabled)
+
 ##### `#poll(hook_id)`
 
 Poll for interactions captured by a single hook.
@@ -232,20 +268,33 @@ Attributes:
 - `dns` (String) - DNS endpoint
 - `http` (String) - HTTP endpoint
 - `https` (String) - HTTPS endpoint
+- `smtp` (String, nil) - Mail address (nil unless the server runs a mail listener)
 - `created_at` (String) - Creation timestamp
+- `expires_at` (String, nil) - Expiry timestamp (long-lived hooks)
+- `metadata` (Hash, nil) - Metadata attached at registration
+
+#### `Hookd::HookActivity`
+
+Represents a long-lived hook that has pending interactions (returned by `#activity`).
+
+Attributes:
+- `hook` (`Hookd::Hook`) - The long-lived hook that fired
+- `pending_count` (Integer) - Number of interactions awaiting poll
+- `last_interaction_at` (String) - Timestamp of the most recent interaction
 
 #### `Hookd::Interaction`
 
-Represents a captured DNS or HTTP interaction.
+Represents a captured DNS, HTTP or SMTP interaction.
 
 Attributes:
-- `type` (String) - Interaction type ("dns" or "http")
+- `type` (String) - Interaction type ("dns", "http" or "smtp")
 - `timestamp` (String) - When the interaction was captured
 - `data` (Hash) - Interaction details
 
 Methods:
 - `#dns?` - Returns true if this is a DNS interaction
 - `#http?` - Returns true if this is an HTTP interaction
+- `#smtp?` - Returns true if this is an SMTP interaction
 
 ### Error Handling
 
@@ -269,3 +318,4 @@ Exception hierarchy:
   - `Hookd::NotFoundError` - 404 Not Found
   - `Hookd::ServerError` - 5xx Server Error
   - `Hookd::ConnectionError` - Network/connection errors
+  - `Hookd::ResponseTooLargeError` - Response above `max_response_bytes`

data/lib/hookd/client.rb

@@ -6,11 +6,19 @@ require 'json'
 module Hookd
   # HTTP client for interacting with Hookd server
   class Client
-    attr_reader :server, :token
+    # Caps the payload materialised as a String. Generous, since a poll can
+    # return many interactions with full bodies. Zero or less disables it.
+    DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024
 
-    def initialize(server:, token:)
+    # How much of an error response is quoted back in the raised message.
+    ERROR_BODY_EXCERPT_BYTES = 1024
+
+    attr_reader :server, :token, :max_response_bytes
+
+    def initialize(server:, token:, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
       @server = server
       @token = token
+      @max_response_bytes = max_response_bytes
       @http = HTTPX.with(
         headers: { 'X-API-Key' => token },
         timeout: {
@@ -22,25 +30,20 @@ module Hookd
 
     # Register one or more hooks
     # @param count [Integer, nil] number of hooks to register (default: 1)
+    # @param ttl [String, nil] lifetime as a Go duration ("168h") or day count
+    #   ("7d"); a value above the server's ephemeral hook_ttl registers a durable
+    #   long-lived hook. Omit for an ephemeral hook.
+    # @param metadata [Hash, nil] arbitrary data stored with the hook and echoed
+    #   back on poll
     # @return [Hookd::Hook, Array<Hookd::Hook>] single hook or array of hooks
     # @raise [Hookd::AuthenticationError] if authentication fails
     # @raise [Hookd::ServerError] if server returns 5xx
     # @raise [Hookd::ConnectionError] if connection fails
     # @raise [ArgumentError] if count is invalid
-    def register(count: nil)
-      body = count.nil? ? nil : { count: count }
-
+    def register(count: nil, ttl: nil, metadata: nil)
       raise ArgumentError, 'count must be a positive integer' if count && (!count.is_a?(Integer) || count < 1)
 
-      response = post('/register', body)
-
-      # Single hook response (backward compatible)
-      return Hook.from_hash(response) if response.key?('id')
-
-      # Multiple hooks response
-      return [] if response['hooks'].nil? || response['hooks'].empty?
-
-      response['hooks'].map { |h| Hook.from_hash(h) }
+      parse_register_response(post('/register', register_body(count, ttl, metadata)))
     end
 
     # Poll for interactions on a hook
@@ -92,8 +95,45 @@ module Hookd
       get('/metrics')
     end
 
+    # List long-lived hooks that currently have pending interactions, so you can
+    # discover which of your long-lived hooks fired without polling each one.
+    # Drain the details with #poll. Returns an empty array when none have fired
+    # (or the server has long-lived hooks disabled).
+    # @return [Array<Hookd::HookActivity>]
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    def activity
+      response = get('/activity')
+
+      hooks = response['hooks']
+      return [] if hooks.nil? || hooks.empty? || !hooks.is_a?(Array)
+
+      hooks.map { |h| HookActivity.from_hash(h) }
+    rescue NoMethodError => e
+      raise Error, "Invalid response format: #{e.message}"
+    end
+
     private
 
+    def register_body(count, ttl, metadata)
+      body = {}
+      body[:count] = count unless count.nil?
+      body[:ttl] = ttl unless ttl.nil?
+      body[:metadata] = metadata unless metadata.nil?
+      body.empty? ? nil : body
+    end
+
+    def parse_register_response(response)
+      # Single hook response (backward compatible)
+      return Hook.from_hash(response) if response.key?('id')
+
+      # Multiple hooks response
+      return [] if response['hooks'].nil? || response['hooks'].empty?
+
+      response['hooks'].map { |h| Hook.from_hash(h) }
+    end
+
     def get(path)
       url = "#{@server}#{path}"
       response = @http.get(url)
@@ -138,24 +178,49 @@ module Hookd
         raise ConnectionError, "Connection failed: #{error.message}"
       end
 
-      body = response.body.to_s
-
       case response.status
       when 200, 201
-        raise Error, 'Empty response body from server' if body.nil? || body.empty?
-
-        JSON.parse(body)
+        parse_body(response)
       when 401
-        raise AuthenticationError, "Authentication failed: #{body}"
+        raise AuthenticationError, "Authentication failed: #{error_excerpt(response)}"
       when 404
-        raise NotFoundError, "Resource not found: #{body}"
+        raise NotFoundError, "Resource not found: #{error_excerpt(response)}"
       when 500..599
-        raise ServerError, "Server error (#{response.status}): #{body}"
+        raise ServerError, "Server error (#{response.status}): #{error_excerpt(response)}"
       else
-        raise Error, "Unexpected response (#{response.status}): #{body}"
+        raise Error, "Unexpected response (#{response.status}): #{error_excerpt(response)}"
       end
+    end
+
+    def parse_body(response)
+      body = read_body(response, @max_response_bytes)
+      raise Error, 'Empty response body from server' if body.empty?
+
+      JSON.parse(body)
     rescue JSON::ParserError => e
       raise Error, "Invalid JSON response: #{e.message}"
     end
+
+    # Accumulates chunk by chunk and stops at the ceiling, raising unless
+    # truncate is set, in which case it returns the bounded slice.
+    def read_body(response, limit, truncate: false)
+      return response.body.to_s if limit <= 0
+
+      body = nil
+      response.body.each do |chunk|
+        # Seed from the first chunk to keep the payload's own encoding.
+        body = body ? body << chunk : chunk.dup
+        next if body.bytesize <= limit
+        return body.byteslice(0, limit).scrub if truncate
+
+        raise ResponseTooLargeError, "Response exceeds the #{limit} byte limit"
+      end
+      body || ''
+    end
+
+    # A large error page must not become a large exception message.
+    def error_excerpt(response)
+      read_body(response, ERROR_BODY_EXCERPT_BYTES, truncate: true)
+    end
   end
 end

data/lib/hookd/error.rb

@@ -15,4 +15,7 @@ module Hookd
 
   # Raised when the server returns a 5xx error
   class ServerError < Error; end
+
+  # Raised when a response exceeds the client's size limit
+  class ResponseTooLargeError < Error; end
 end

data/lib/hookd/hook.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 module Hookd
-  # Represents a registered hook with DNS and HTTP endpoints
+  # Represents a registered hook with its endpoints. smtp is set only when the
+  # server runs a mail listener. expires_at and metadata are populated for
+  # long-lived hooks (registered with a ttl) and nil otherwise.
   class Hook
-    attr_reader :id, :dns, :http, :https, :created_at
+    attr_reader :id, :dns, :http, :https, :smtp, :created_at, :expires_at, :metadata
 
-    def initialize(id:, dns:, http:, https:, created_at:)
+    def initialize(id:, dns:, http:, https:, created_at:, smtp: nil, expires_at: nil, metadata: nil)
       @id = id
       @dns = dns
       @http = http
       @https = https
+      @smtp = smtp
       @created_at = created_at
+      @expires_at = expires_at
+      @metadata = metadata
     end
 
     # Create a Hook from API response hash
@@ -22,7 +27,10 @@ module Hookd
         dns: hash['dns'],
         http: hash['http'],
         https: hash['https'],
-        created_at: hash['created_at']
+        smtp: hash['smtp'],
+        created_at: hash['created_at'],
+        expires_at: hash['expires_at'],
+        metadata: hash['metadata']
       )
     end
 

data/lib/hookd/hook_activity.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Summarises a long-lived hook that currently has pending interactions,
+  # returned by Client#activity.
+  class HookActivity
+    attr_reader :hook, :pending_count, :last_interaction_at
+
+    def initialize(hook:, pending_count:, last_interaction_at:)
+      @hook = hook
+      @pending_count = pending_count
+      @last_interaction_at = last_interaction_at
+    end
+
+    # Create a HookActivity from an API response hash
+    def self.from_hash(hash)
+      raise ArgumentError, "Invalid hash: expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      new(
+        hook: Hook.from_hash(hash['hook']),
+        pending_count: hash['pending_count'],
+        last_interaction_at: hash['last_interaction_at']
+      )
+    end
+
+    def to_s
+      "#<Hookd::HookActivity hook=#{hook.id} pending=#{pending_count}>"
+    end
+  end
+end

data/lib/hookd/interaction.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hookd
-  # Represents a captured DNS or HTTP interaction
+  # Represents a captured DNS, HTTP or SMTP interaction
   class Interaction
     attr_reader :type, :timestamp, :source_ip, :data
 
@@ -32,6 +32,11 @@ module Hookd
       type == 'http'
     end
 
+    # Check if this is an SMTP interaction
+    def smtp?
+      type == 'smtp'
+    end
+
     def to_s
       "#<Hookd::Interaction type=#{type} timestamp=#{timestamp} source_ip=#{source_ip}>"
     end

data/lib/hookd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hookd
-  VERSION = '1.2.2'
+  VERSION = '1.4.0'
 end

data/lib/hookd.rb

@@ -3,6 +3,7 @@
 require_relative 'hookd/version'
 require_relative 'hookd/error'
 require_relative 'hookd/hook'
+require_relative 'hookd/hook_activity'
 require_relative 'hookd/interaction'
 require_relative 'hookd/client'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
@@ -23,8 +23,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Ruby client library for Hookd, a DNS/HTTP interaction server for security
-  testing and debugging
+description: Ruby client library for Hookd, a DNS/SMTP/HTTP interaction server for
+  security testing and debugging
 email:
 - contact@jomar.fr
 executables: []
@@ -36,6 +36,7 @@ files:
 - lib/hookd/client.rb
 - lib/hookd/error.rb
 - lib/hookd/hook.rb
+- lib/hookd/hook_activity.rb
 - lib/hookd/interaction.rb
 - lib/hookd/version.rb
 homepage: https://github.com/JoshuaMart/Hookd