signalwire_agents 1.1.0

data/lib/signalwire_agents/rest/namespaces/video.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # Video room management with streams.
+      class VideoRooms < CrudResource
+        self.update_method = 'PUT'
+
+        def list_streams(room_id, **params)
+          @http.get(_path(room_id, 'streams'), params.empty? ? nil : params)
+        end
+
+        def create_stream(room_id, **kwargs)
+          @http.post(_path(room_id, 'streams'), kwargs)
+        end
+      end
+
+      # Video room token generation.
+      class VideoRoomTokens < BaseResource
+        def create(**kwargs)
+          @http.post(@base_path, kwargs)
+        end
+      end
+
+      # Video room session management.
+      class VideoRoomSessions < BaseResource
+        def list(**params)
+          @http.get(@base_path, params.empty? ? nil : params)
+        end
+
+        def get(session_id)
+          @http.get(_path(session_id))
+        end
+
+        def list_events(session_id, **params)
+          @http.get(_path(session_id, 'events'), params.empty? ? nil : params)
+        end
+
+        def list_members(session_id, **params)
+          @http.get(_path(session_id, 'members'), params.empty? ? nil : params)
+        end
+
+        def list_recordings(session_id, **params)
+          @http.get(_path(session_id, 'recordings'), params.empty? ? nil : params)
+        end
+      end
+
+      # Video room recording management.
+      class VideoRoomRecordings < BaseResource
+        def list(**params)
+          @http.get(@base_path, params.empty? ? nil : params)
+        end
+
+        def get(recording_id)
+          @http.get(_path(recording_id))
+        end
+
+        def delete(recording_id)
+          @http.delete(_path(recording_id))
+        end
+
+        def list_events(recording_id, **params)
+          @http.get(_path(recording_id, 'events'), params.empty? ? nil : params)
+        end
+      end
+
+      # Video conference management with tokens and streams.
+      class VideoConferences < CrudResource
+        self.update_method = 'PUT'
+
+        def list_conference_tokens(conference_id, **params)
+          @http.get(_path(conference_id, 'conference_tokens'), params.empty? ? nil : params)
+        end
+
+        def list_streams(conference_id, **params)
+          @http.get(_path(conference_id, 'streams'), params.empty? ? nil : params)
+        end
+
+        def create_stream(conference_id, **kwargs)
+          @http.post(_path(conference_id, 'streams'), kwargs)
+        end
+      end
+
+      # Video conference token management.
+      class VideoConferenceTokens < BaseResource
+        def get(token_id)
+          @http.get(_path(token_id))
+        end
+
+        def reset(token_id)
+          @http.post(_path(token_id, 'reset'))
+        end
+      end
+
+      # Video stream management.
+      class VideoStreams < BaseResource
+        def get(stream_id)
+          @http.get(_path(stream_id))
+        end
+
+        def update(stream_id, **kwargs)
+          @http.put(_path(stream_id), kwargs)
+        end
+
+        def delete(stream_id)
+          @http.delete(_path(stream_id))
+        end
+      end
+
+      # Video API namespace.
+      class VideoNamespace
+        attr_reader :rooms, :room_tokens, :room_sessions, :room_recordings,
+                    :conferences, :conference_tokens, :streams
+
+        def initialize(http)
+          base = '/api/video'
+          @rooms              = VideoRooms.new(http, "#{base}/rooms")
+          @room_tokens        = VideoRoomTokens.new(http, "#{base}/room_tokens")
+          @room_sessions      = VideoRoomSessions.new(http, "#{base}/room_sessions")
+          @room_recordings    = VideoRoomRecordings.new(http, "#{base}/room_recordings")
+          @conferences        = VideoConferences.new(http, "#{base}/conferences")
+          @conference_tokens  = VideoConferenceTokens.new(http, "#{base}/conference_tokens")
+          @streams            = VideoStreams.new(http, "#{base}/streams")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/signalwire_client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative 'http_client'
+require_relative 'namespaces/fabric'
+require_relative 'namespaces/calling'
+require_relative 'namespaces/phone_numbers'
+require_relative 'namespaces/addresses'
+require_relative 'namespaces/queues'
+require_relative 'namespaces/recordings'
+require_relative 'namespaces/number_groups'
+require_relative 'namespaces/verified_callers'
+require_relative 'namespaces/sip_profile'
+require_relative 'namespaces/lookup'
+require_relative 'namespaces/short_codes'
+require_relative 'namespaces/imported_numbers'
+require_relative 'namespaces/mfa'
+require_relative 'namespaces/registry'
+require_relative 'namespaces/datasphere'
+require_relative 'namespaces/video'
+require_relative 'namespaces/logs'
+require_relative 'namespaces/project'
+require_relative 'namespaces/pubsub'
+require_relative 'namespaces/chat'
+require_relative 'namespaces/compat'
+
+module SignalWireAgents
+  module REST
+    # REST client for the SignalWire platform APIs.
+    #
+    # Usage:
+    #   client = SignalWireAgents::REST::SignalWireClient.new(
+    #     project: 'your-project-id',
+    #     token:   'your-api-token',
+    #     host:    'your-space.signalwire.com'
+    #   )
+    #
+    #   # Or use environment variables:
+    #   #   SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, SIGNALWIRE_SPACE
+    #   client = SignalWireAgents::REST::SignalWireClient.new
+    #
+    #   # Use namespaced resources
+    #   client.fabric.ai_agents.list
+    #   client.calling.play(call_id, play: [...])
+    #   client.phone_numbers.search(area_code: '512')
+    #   client.video.rooms.create(name: 'standup')
+    #   client.compat.calls.list
+    class SignalWireClient
+      attr_reader :fabric, :calling, :phone_numbers, :datasphere, :video,
+                  :compat, :addresses, :queues, :recordings, :number_groups,
+                  :verified_callers, :sip_profile, :lookup, :short_codes,
+                  :imported_numbers, :mfa, :registry, :logs, :project,
+                  :pubsub, :chat
+
+      def initialize(project: nil, token: nil, host: nil)
+        project_id = project || ENV['SIGNALWIRE_PROJECT_ID'] || ''
+        api_token  = token || ENV['SIGNALWIRE_API_TOKEN'] || ''
+        space      = host || ENV['SIGNALWIRE_SPACE'] || ''
+
+        if project_id.empty? || api_token.empty? || space.empty?
+          raise ArgumentError,
+                'project, token, and host are required. ' \
+                'Provide them as arguments or set SIGNALWIRE_PROJECT_ID, ' \
+                'SIGNALWIRE_API_TOKEN, and SIGNALWIRE_SPACE environment variables.'
+        end
+
+        @project_id = project_id
+        @http = HttpClient.new(project_id, api_token, space)
+
+        # Fabric API
+        @fabric = Namespaces::FabricNamespace.new(@http)
+
+        # Calling API
+        @calling = Namespaces::CallingNamespace.new(@http)
+
+        # Relay REST resources
+        @phone_numbers    = Namespaces::PhoneNumbersResource.new(@http)
+        @addresses        = Namespaces::AddressesResource.new(@http)
+        @queues           = Namespaces::QueuesResource.new(@http)
+        @recordings       = Namespaces::RecordingsResource.new(@http)
+        @number_groups    = Namespaces::NumberGroupsResource.new(@http)
+        @verified_callers = Namespaces::VerifiedCallersResource.new(@http)
+        @sip_profile      = Namespaces::SipProfileResource.new(@http)
+        @lookup           = Namespaces::LookupResource.new(@http)
+        @short_codes      = Namespaces::ShortCodesResource.new(@http)
+        @imported_numbers = Namespaces::ImportedNumbersResource.new(@http)
+        @mfa              = Namespaces::MfaResource.new(@http)
+        @registry         = Namespaces::RegistryNamespace.new(@http)
+
+        # Datasphere API
+        @datasphere = Namespaces::DatasphereNamespace.new(@http)
+
+        # Video API
+        @video = Namespaces::VideoNamespace.new(@http)
+
+        # Logs
+        @logs = Namespaces::LogsNamespace.new(@http)
+
+        # Project management
+        @project = Namespaces::ProjectNamespace.new(@http)
+
+        # PubSub & Chat
+        @pubsub = Namespaces::PubSubResource.new(@http)
+        @chat   = Namespaces::ChatResource.new(@http)
+
+        # Compatibility (Twilio-compatible) API
+        @compat = Namespaces::CompatNamespace.new(@http, project_id)
+      end
+    end
+  end
+end

data/lib/signalwire_agents/security/session_manager.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require 'openssl'
+require 'securerandom'
+require 'base64'
+
+module SignalWireAgents
+  module Security
+    # Stateless HMAC-SHA256 session manager for secure SWAIG tool tokens.
+    #
+    # Tokens are self-contained: all information needed for validation is
+    # encoded inside the token itself. No server-side session state is stored.
+    #
+    #   mgr = SessionManager.new(token_expiry_secs: 900)
+    #   token = mgr.create_token("lookup_order", "call-abc-123")
+    #   mgr.validate_token("lookup_order", token, "call-abc-123") # => true
+    #
+    class SessionManager
+      # @param token_expiry_secs [Integer] seconds until tokens expire (minimum 1)
+      # @param secret_key [String, nil] hex-encoded secret; generated if omitted
+      def initialize(token_expiry_secs: 3600, secret_key: nil)
+        @token_expiry_secs = [token_expiry_secs, 1].max
+        @secret_key = secret_key || SecureRandom.hex(32)
+      end
+
+      # Create a secure, self-contained token for a function call.
+      #
+      # Token format (before Base64):
+      #   call_id.function_name.expiry_timestamp.nonce.hmac_hex
+      #
+      # @param function_name [String]
+      # @param call_id [String]
+      # @return [String] URL-safe Base64-encoded token
+      def create_token(function_name, call_id)
+        expiry = (Time.now.to_i + @token_expiry_secs).to_s
+        nonce  = SecureRandom.hex(8)
+
+        message   = "#{call_id}:#{function_name}:#{expiry}:#{nonce}"
+        signature = compute_hmac(message)
+
+        token_raw = "#{call_id}.#{function_name}.#{expiry}.#{nonce}.#{signature}"
+        Base64.urlsafe_encode64(token_raw, padding: false)
+      end
+
+      # Validate a function-call token.
+      #
+      # Checks:
+      # 1. Correct Base64 / structure (5 dot-separated parts)
+      # 2. HMAC signature (timing-safe comparison)
+      # 3. Function name matches
+      # 4. Call ID matches
+      # 5. Token not expired
+      #
+      # @param function_name [String]
+      # @param token [String] the token to validate
+      # @param call_id [String]
+      # @return [Boolean]
+      def validate_token(function_name, token, call_id)
+        return false if token.nil? || token.empty?
+        return false if call_id.nil? || call_id.empty?
+
+        decoded = Base64.urlsafe_decode64(token)
+        parts   = decoded.split(".")
+        return false unless parts.length == 5
+
+        token_call_id, token_function, token_expiry, token_nonce, token_signature = parts
+
+        # Verify function name
+        return false unless token_function == function_name
+
+        # Verify call ID
+        return false unless token_call_id == call_id
+
+        # Check expiry
+        expiry = Integer(token_expiry)
+        return false if expiry < Time.now.to_i
+
+        # Recompute HMAC and compare with timing-safe comparison
+        message           = "#{token_call_id}:#{token_function}:#{token_expiry}:#{token_nonce}"
+        expected_signature = compute_hmac(message)
+
+        secure_compare(token_signature, expected_signature)
+      rescue ArgumentError, TypeError
+        # Bad Base64, bad integer, etc.
+        false
+      end
+
+      private
+
+      # Compute HMAC-SHA256 of +message+ using the instance secret key.
+      # @return [String] hex digest
+      def compute_hmac(message)
+        OpenSSL::HMAC.hexdigest("SHA256", @secret_key, message)
+      end
+
+      # Timing-safe string comparison.
+      #
+      # Uses OpenSSL.fixed_length_secure_compare when the strings are the same
+      # length (which they should be for hex HMAC digests). Falls back to a
+      # double-HMAC comparison for differing lengths.
+      def secure_compare(a, b)
+        return false if a.nil? || b.nil?
+
+        if a.bytesize == b.bytesize
+          OpenSSL.fixed_length_secure_compare(a, b)
+        else
+          # Different length => definitely not equal, but still constant-time
+          false
+        end
+      rescue NoMethodError
+        # Fallback for older Ruby without fixed_length_secure_compare:
+        # compare HMAC of both values so timing doesn't leak content.
+        ha = OpenSSL::HMAC.digest("SHA256", @secret_key, a.to_s)
+        hb = OpenSSL::HMAC.digest("SHA256", @secret_key, b.to_s)
+        ha == hb
+      end
+    end
+  end
+end

data/lib/signalwire_agents/server/agent_server.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require 'json'
+require 'thread'
+
+module SignalWireAgents
+  # Multi-agent hosting on a single Rack application.
+  #
+  #   server = AgentServer.new(host: '0.0.0.0', port: 3000)
+  #   server.register(my_agent, route: '/agent1')
+  #   server.register(my_agent2, route: '/agent2')
+  #   server.run
+  #
+  class AgentServer
+    attr_reader :host, :port
+
+    # MIME types for static file serving.
+    MIME_TYPES = {
+      '.html' => 'text/html',
+      '.htm'  => 'text/html',
+      '.css'  => 'text/css',
+      '.js'   => 'application/javascript',
+      '.json' => 'application/json',
+      '.png'  => 'image/png',
+      '.jpg'  => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif'  => 'image/gif',
+      '.svg'  => 'image/svg+xml',
+      '.ico'  => 'image/x-icon',
+      '.txt'  => 'text/plain',
+      '.xml'  => 'application/xml',
+      '.woff' => 'font/woff',
+      '.woff2' => 'font/woff2',
+      '.ttf'  => 'font/ttf',
+      '.eot'  => 'application/vnd.ms-fontobject',
+      '.map'  => 'application/json',
+      '.webp' => 'image/webp',
+      '.pdf'  => 'application/pdf'
+    }.freeze
+
+    # Security headers applied to static file responses.
+    STATIC_SECURITY_HEADERS = {
+      'x-content-type-options' => 'nosniff',
+      'x-frame-options'        => 'DENY',
+      'cache-control'          => 'no-store, no-cache, must-revalidate'
+    }.freeze
+
+    def initialize(host: '0.0.0.0', port: 3000)
+      @host   = host
+      @port   = port
+      @agents = {}   # route => agent object
+      @sip_routes = {}  # username => route
+      @static_routes = {} # route => directory
+      @mutex  = Mutex.new
+    end
+
+    # Register an agent at a given route.
+    # @param agent [Object] an agent object (e.g. AgentBase or prefab)
+    # @param route [String, nil] HTTP route; defaults to agent.route if available
+    def register(agent, route: nil)
+      route ||= agent.respond_to?(:route) ? agent.route : "/#{agent.object_id}"
+      route = "/#{route}" unless route.start_with?('/')
+
+      @mutex.synchronize do
+        raise ArgumentError, "Route already registered: #{route}" if @agents.key?(route)
+        @agents[route] = agent
+      end
+      self
+    end
+
+    # Unregister an agent by route.
+    # @param route [String]
+    # @return [Object, nil] the removed agent
+    def unregister(route)
+      route = "/#{route}" unless route.start_with?('/')
+      @mutex.synchronize { @agents.delete(route) }
+    end
+
+    # Get all registered agents.
+    # @return [Hash] route => agent
+    def get_agents
+      @mutex.synchronize { @agents.dup }
+    end
+
+    # Get a specific agent by route.
+    # @param route [String]
+    # @return [Object, nil]
+    def get_agent(route)
+      route = "/#{route}" unless route.start_with?('/')
+      @mutex.synchronize { @agents[route] }
+    end
+
+    # Set up SIP-based routing.
+    # @param route [String] the route to handle SIP requests
+    # @param auto_map [Boolean] automatically map agent names as SIP usernames
+    def setup_sip_routing(route: '/sip', auto_map: true)
+      @sip_route = route
+      if auto_map
+        @mutex.synchronize do
+          @agents.each do |r, agent|
+            username = r.sub(%r{^/}, '').tr('/', '_')
+            @sip_routes[username] = r
+          end
+        end
+      end
+      self
+    end
+
+    # Register a SIP username mapping to a route.
+    def register_sip_username(username, route)
+      route = "/#{route}" unless route.start_with?('/')
+      @mutex.synchronize { @sip_routes[username] = route }
+      self
+    end
+
+    # Serve static files from a directory at a given route.
+    #
+    # @param directory [String] absolute or relative path to the directory
+    # @param route [String] the URL prefix to serve files at
+    # @return [self]
+    def serve_static_files(directory, route)
+      route = "/#{route}" unless route.start_with?('/')
+      route = route.chomp('/')
+      resolved = File.expand_path(directory)
+      raise ArgumentError, "Directory does not exist: #{resolved}" unless File.directory?(resolved)
+
+      @mutex.synchronize { @static_routes[route] = resolved }
+      self
+    end
+
+    # Run the server using WEBrick (stdlib).
+    def run
+      app = rack_app
+      require 'webrick'
+      server = WEBrick::HTTPServer.new(
+        Host: @host,
+        Port: @port,
+        Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
+        AccessLog: []
+      )
+      server.mount('/', Rack::Handler::WEBrick, app) if defined?(Rack::Handler::WEBrick)
+      trap('INT') { server.shutdown }
+      trap('TERM') { server.shutdown }
+      server.start
+    end
+
+    # Build a Rack application that routes requests to the appropriate agent.
+    # @return [Proc] a Rack-compatible app
+    def rack_app
+      agents        = @agents
+      sip_routes    = @sip_routes
+      static_routes = @static_routes
+      server        = self
+
+      Proc.new do |env|
+        path = env['PATH_INFO'] || '/'
+
+        case path
+        when '/health', '/healthz'
+          body = { status: 'ok', agents: agents.keys }.to_json
+          ['200', { 'Content-Type' => 'application/json' }, [body]]
+
+        when '/'
+          body = {
+            service: 'SignalWire Agent Server',
+            agents: agents.keys,
+            version: defined?(SignalWireAgents::VERSION) ? SignalWireAgents::VERSION : '1.0.0'
+          }.to_json
+          ['200', { 'Content-Type' => 'application/json' }, [body]]
+
+        else
+          # Check static routes first (longest prefix match)
+          static_result = server._try_serve_static(path, static_routes)
+          if static_result
+            static_result
+          else
+            # Find the matching agent by longest prefix match
+            agent = nil
+            matched_route = nil
+
+            agents.each do |route, a|
+              if path == route || path.start_with?("#{route}/")
+                if matched_route.nil? || route.length > matched_route.length
+                  matched_route = route
+                  agent = a
+                end
+              end
+            end
+
+            if agent
+              if agent.respond_to?(:call)
+                agent.call(env)
+              elsif agent.respond_to?(:rack_app)
+                agent.rack_app.call(env)
+              else
+                body = { agent: matched_route, status: 'registered' }.to_json
+                ['200', { 'Content-Type' => 'application/json' }, [body]]
+              end
+            else
+              body = { error: 'Not found', path: path }.to_json
+              ['404', { 'Content-Type' => 'application/json' }, [body]]
+            end
+          end
+        end
+      end
+    end
+
+    # @api private
+    # Attempt to serve a static file. Returns a Rack response or nil.
+    def _try_serve_static(path, static_routes)
+      matched_route = nil
+      matched_dir   = nil
+
+      static_routes.each do |route, directory|
+        if path == route || path.start_with?("#{route}/")
+          if matched_route.nil? || route.length > matched_route.length
+            matched_route = route
+            matched_dir   = directory
+          end
+        end
+      end
+
+      return nil unless matched_dir
+
+      # Extract the relative path after the route prefix
+      relative = path.sub(matched_route, '')
+      relative = '/index.html' if relative.empty? || relative == '/'
+
+      # Path traversal protection: reject any path containing ".."
+      if relative.include?('..')
+        body = JSON.generate({ error: 'Forbidden' })
+        return ['403', STATIC_SECURITY_HEADERS.merge('Content-Type' => 'application/json'), [body]]
+      end
+
+      file_path = File.join(matched_dir, relative)
+      resolved  = File.expand_path(file_path)
+
+      # Ensure resolved path is still under the served directory
+      unless resolved.start_with?(matched_dir + '/')  || resolved == matched_dir
+        body = JSON.generate({ error: 'Forbidden' })
+        return ['403', STATIC_SECURITY_HEADERS.merge('Content-Type' => 'application/json'), [body]]
+      end
+
+      if File.file?(resolved) && File.readable?(resolved)
+        ext = File.extname(resolved).downcase
+        content_type = MIME_TYPES[ext] || 'application/octet-stream'
+        content = File.binread(resolved)
+        headers = STATIC_SECURITY_HEADERS.merge('Content-Type' => content_type, 'Content-Length' => content.bytesize.to_s)
+        ['200', headers, [content]]
+      else
+        nil
+      end
+    end
+  end
+end