alta_labs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee3307c6dee96fcff9e6ef2a96e283a119b7c1c9d8f67af89f306342c1ffe4a5
+  data.tar.gz: 38841e7b4d9ee246c9b0d079e7fa8401abe77d5d3b93af43fd8c32424adb6b6c
+SHA512:
+  metadata.gz: 4503a64818d9b600bfd87dbf0ea6a34b50022a16d6d4e673a4689630be7f57850f859a2116ee7b7d8b5004c46f5bf56dfa2d785ce119b119586cfaa63597cd1d
+  data.tar.gz: 4bcec3a38df3126f40a44485b673b96dd8d7ca3c6105972f2bc6be5e380aa624e69e7e3a1e4997568ce39196d499ee04edc216d659ef4fe7837486afdc4e6250

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - Unreleased
+
+- Initial release
+- Cognito SRP authentication (no AWS SDK dependency)
+- Site management (list, get, stats)
+- Device management (list, search)
+- WiFi/SSID management (list, get)
+- Client device listing
+- Account info retrieval

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dale Stevens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+[![Gem Version](https://img.shields.io/gem/v/alta_labs.svg)](https://rubygems.org/gems/alta_labs)
+[![Build Status](https://github.com/TwilightCoders/alta_labs/workflows/CI/badge.svg)](https://github.com/TwilightCoders/alta_labs/actions)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/TwilightCoders/alta_labs)
+
+# AltaLabs
+
+A Ruby SDK for the [Alta Labs](https://alta.inc) cloud management API. Manage sites, devices, WiFi networks, and more programmatically.
+
+> **Note:** Alta Labs does not currently publish public API documentation. This library was built by reverse-engineering the web management portal at `manage.alta.inc`. While functional, the API surface may change without notice.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'alta_labs'
+```
+
+Or install directly:
+
+```
+$ gem install alta_labs
+```
+
+## Usage
+
+### Authentication
+
+The SDK authenticates with Alta Labs via AWS Cognito SRP — the same mechanism used by the web portal. No AWS SDK dependency is required; SRP is implemented natively.
+
+```ruby
+require 'alta_labs'
+
+client = AltaLabs::Client.new(
+  email: 'you@example.com',
+  password: 'your-password'
+)
+
+# Authentication happens automatically on the first API call,
+# or you can authenticate explicitly:
+client.authenticate
+```
+
+You can also configure via environment variables or a block:
+
+```ruby
+# Environment variables (ALTA_LABS_EMAIL, ALTA_LABS_PASSWORD)
+client = AltaLabs::Client.new
+
+# Block configuration
+AltaLabs.configure do |config|
+  config.email = 'you@example.com'
+  config.password = 'your-password'
+  config.timeout = 60
+end
+```
+
+### Sites
+
+```ruby
+# List all sites
+sites = client.sites.list
+# => [{"id" => "abc123", "name" => "Main Office", "online" => 5, ...}]
+
+# Get site detail
+site = client.sites.find(id: 'abc123')
+# => {"id" => "abc123", "tz" => "America/Denver", "vlans" => [...], ...}
+
+# Site audit log
+audit = client.sites.audit(id: 'abc123')
+audit['trail'].each do |entry|
+  puts "[#{entry['ts']}] #{entry['action']} #{entry['type']}"
+end
+
+# Create a site
+client.sites.create(name: 'New Site', type: 'residential')
+
+# Rename a site
+client.sites.rename(id: 'abc123', name: 'Updated Name')
+```
+
+### Devices
+
+```ruby
+# List devices for a site
+devices = client.devices.list(site_id: 'abc123')
+
+# Add a device by serial number
+client.devices.add_serial(site_id: 'abc123', serial: 'ALTA-XXXX')
+
+# Move a device between sites
+client.devices.move(id: 'device-id', site_id: 'new-site-id')
+```
+
+### WiFi / SSIDs
+
+```ruby
+# List SSIDs for a site
+result = client.wifi.list(site_id: 'abc123')
+result['ssids'].each do |ssid|
+  puts "#{ssid['ssid']} (#{ssid.dig('config', 'security')})"
+end
+
+# Get a specific SSID
+ssid = client.wifi.find(id: 'ssid-id')
+```
+
+### Account
+
+```ruby
+# Get account info (requires access_token)
+info = client.account.info
+```
+
+### Content Filtering
+
+```ruby
+# Get content filter settings
+filter = client.filters.get_filter(site_id: 'abc123')
+# => {"blockedRegions" => ["CN"], "blockWired" => true, ...}
+```
+
+### Profiles
+
+```ruby
+profiles = client.profiles.list(site_ids: ['abc123'])
+```
+
+### Floor Plans
+
+```ruby
+floors = client.floor_plans.floors(site_id: 'abc123')
+```
+
+## Token Management
+
+Tokens are automatically refreshed when they expire. The SDK handles:
+
+- Initial SRP authentication with Cognito
+- JWT token storage and expiration tracking
+- Automatic token refresh using the refresh token
+- MFA challenges (raises `AltaLabs::MfaRequiredError` with session data)
+
+### MFA Support
+
+If MFA is enabled on the account:
+
+```ruby
+begin
+  client.authenticate
+rescue AltaLabs::MfaRequiredError => e
+  # Prompt user for MFA code
+  client.auth.verify_mfa(
+    code: '123456',
+    session: e.session,
+    challenge_name: e.challenge_name
+  )
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.sites.find(id: 'nonexistent')
+rescue AltaLabs::AuthenticationError => e
+  # Invalid credentials or expired session
+rescue AltaLabs::NotFoundError => e
+  # Resource not found
+rescue AltaLabs::RateLimitError => e
+  # Too many requests
+rescue AltaLabs::ServerError => e
+  # Alta Labs server error
+rescue AltaLabs::ApiError => e
+  # Generic API error
+  puts e.status # HTTP status code
+  puts e.body   # Response body
+end
+```
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `email` | `ENV['ALTA_LABS_EMAIL']` | Account email |
+| `password` | `ENV['ALTA_LABS_PASSWORD']` | Account password |
+| `api_url` | `https://manage.alta.inc` | API base URL |
+| `timeout` | `30` | Request timeout (seconds) |
+| `open_timeout` | `10` | Connection open timeout (seconds) |
+
+## Self-Hosted Controller
+
+To use with a self-hosted Alta Control instance:
+
+```ruby
+client = AltaLabs::Client.new(
+  email: 'you@example.com',
+  password: 'your-password',
+)
+client.config.api_url = 'https://your-controller.local'
+```
+
+## Development
+
+```
+$ bundle install
+$ bundle exec rspec
+$ bin/console
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/alta_labs/auth/cognito.rb

@@ -0,0 +1,178 @@
+module AltaLabs
+  module Auth
+    # Authenticates with AWS Cognito using the SRP protocol.
+    # Returns JWT tokens (id_token, access_token, refresh_token).
+    class Cognito
+      attr_reader :config, :tokens
+
+      def initialize(config)
+        @config = config
+        @tokens = {}
+      end
+
+      # Perform full SRP authentication flow.
+      # @return [Hash] tokens hash with :id_token, :access_token, :refresh_token
+      def authenticate(email: config.email, password: config.password)
+        raise InvalidCredentialsError, 'Email and password are required' unless email && password
+
+        srp = SRP.new(config.pool_name)
+
+        # Step 1: Initiate auth
+        challenge = initiate_auth(email, srp.srp_a)
+
+        case challenge['ChallengeName']
+        when 'PASSWORD_VERIFIER'
+          respond_to_password_verifier(srp, challenge, email, password)
+        when 'SOFTWARE_TOKEN_MFA', 'SMS_MFA'
+          raise MfaRequiredError.new(
+            session: challenge['Session'],
+            challenge_name: challenge['ChallengeName']
+          )
+        else
+          raise AuthenticationError, "Unexpected challenge: #{challenge['ChallengeName']}"
+        end
+      end
+
+      # Refresh tokens using the refresh_token.
+      # @return [Hash] refreshed tokens
+      def refresh(refresh_token = nil)
+        refresh_token ||= @tokens[:refresh_token]
+        raise AuthenticationError, 'No refresh token available' unless refresh_token
+
+        result = cognito_request('InitiateAuth', {
+          'AuthFlow' => 'REFRESH_TOKEN_AUTH',
+          'ClientId' => config.client_id,
+          'AuthParameters' => {
+            'REFRESH_TOKEN' => refresh_token
+          }
+        })
+
+        auth_result = result['AuthenticationResult']
+        @tokens = {
+          id_token: auth_result['IdToken'],
+          access_token: auth_result['AccessToken'],
+          refresh_token: refresh_token, # Cognito doesn't return a new refresh token
+          expires_at: Time.now + auth_result['ExpiresIn'].to_i
+        }
+      end
+
+      # Respond to MFA challenge.
+      # @param code [String] the MFA code
+      # @param session [String] session from MfaRequiredError
+      # @param challenge_name [String] challenge type from MfaRequiredError
+      # @return [Hash] tokens
+      def verify_mfa(code:, session:, challenge_name: 'SOFTWARE_TOKEN_MFA')
+        result = cognito_request('RespondToAuthChallenge', {
+          'ChallengeName' => challenge_name,
+          'ClientId' => config.client_id,
+          'Session' => session,
+          'ChallengeResponses' => {
+            'USERNAME' => config.email,
+            'SOFTWARE_TOKEN_MFA_CODE' => code
+          }
+        })
+
+        extract_tokens(result['AuthenticationResult'])
+      end
+
+      def id_token
+        @tokens[:id_token]
+      end
+
+      def token_expired?
+        return true unless @tokens[:expires_at]
+
+        Time.now >= @tokens[:expires_at] - 60 # 60s buffer
+      end
+
+      private
+
+      def initiate_auth(email, srp_a)
+        cognito_request('InitiateAuth', {
+          'AuthFlow' => 'USER_SRP_AUTH',
+          'ClientId' => config.client_id,
+          'AuthParameters' => {
+            'USERNAME' => email,
+            'SRP_A' => srp_a
+          }
+        })
+      end
+
+      def respond_to_password_verifier(srp, challenge, email, password)
+        params = challenge['ChallengeParameters']
+        timestamp = Time.now.utc.strftime('%a %b %-d %H:%M:%S UTC %Y')
+
+        signature = srp.compute_claim(
+          user_id: params['USER_ID_FOR_SRP'],
+          password: password,
+          srp_b: params['SRP_B'],
+          salt: params['SALT'],
+          secret_block: params['SECRET_BLOCK'],
+          timestamp: timestamp
+        )
+
+        result = cognito_request('RespondToAuthChallenge', {
+          'ChallengeName' => 'PASSWORD_VERIFIER',
+          'ClientId' => config.client_id,
+          'ChallengeResponses' => {
+            'USERNAME' => params['USER_ID_FOR_SRP'],
+            'PASSWORD_CLAIM_SECRET_BLOCK' => params['SECRET_BLOCK'],
+            'PASSWORD_CLAIM_SIGNATURE' => signature,
+            'TIMESTAMP' => timestamp
+          }
+        })
+
+        if result['ChallengeName']
+          case result['ChallengeName']
+          when 'SOFTWARE_TOKEN_MFA', 'SMS_MFA'
+            raise MfaRequiredError.new(
+              session: result['Session'],
+              challenge_name: result['ChallengeName']
+            )
+          else
+            raise AuthenticationError, "Unexpected post-auth challenge: #{result['ChallengeName']}"
+          end
+        end
+
+        extract_tokens(result['AuthenticationResult'])
+      end
+
+      def extract_tokens(auth_result)
+        raise AuthenticationError, 'No authentication result' unless auth_result
+
+        @tokens = {
+          id_token: auth_result['IdToken'],
+          access_token: auth_result['AccessToken'],
+          refresh_token: auth_result['RefreshToken'],
+          expires_at: Time.now + auth_result['ExpiresIn'].to_i
+        }
+      end
+
+      def cognito_request(action, body)
+        response = cognito_connection.post('') do |req|
+          req.headers['X-Amz-Target'] = "AWSCognitoIdentityProviderService.#{action}"
+          req.headers['Content-Type'] = 'application/x-amz-json-1.1'
+          req.body = body.to_json
+        end
+
+        result = JSON.parse(response.body)
+
+        if response.status != 200
+          error_type = result['__type']&.split('#')&.last || 'Unknown'
+          error_msg = result['message'] || result['Message'] || 'Authentication failed'
+          raise AuthenticationError, "#{error_type}: #{error_msg}"
+        end
+
+        result
+      end
+
+      def cognito_connection
+        @cognito_connection ||= Faraday.new(url: config.cognito_endpoint) do |f|
+          f.options.timeout = config.timeout
+          f.options.open_timeout = config.open_timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/alta_labs/auth/srp.rb

@@ -0,0 +1,134 @@
+module AltaLabs
+  module Auth
+    # Implements the Secure Remote Password (SRP-6a) protocol as used by
+    # AWS Cognito. Uses only Ruby stdlib (OpenSSL) -- no AWS SDK required.
+    #
+    # Matches the amazon-cognito-identity-js reference implementation.
+    class SRP
+      # Cognito's 3072-bit SRP prime (hex)
+      N_HEX = 'FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1' \
+              '29024E088A67CC74020BBEA63B139B22514A08798E3404DD' \
+              'EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245' \
+              'E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED' \
+              'EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D' \
+              'C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F' \
+              '83655D23DCA3AD961C62F356208552BB9ED529077096966D' \
+              '670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B' \
+              'E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9' \
+              'DE2BCBF6955817183995497CEA956AE515D2261898FA0510' \
+              '15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64' \
+              'ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7' \
+              'ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B' \
+              'F12FFA06D98A0864D87602733EC86A64521F2B18177B200CB' \
+              'BE117577A615D6C770988C0BAD946E208E24FA074E5AB3143' \
+              'DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF'
+
+      G_HEX = '2'
+      INFO_BITS = 'Caldera Derived Key'
+
+      attr_reader :pool_name, :big_a, :small_a
+
+      def initialize(pool_name)
+        @pool_name = pool_name
+        @n = OpenSSL::BN.new(N_HEX, 16)
+        @g = OpenSSL::BN.new(G_HEX, 16)
+        @k = compute_k
+        generate_a
+      end
+
+      def srp_a
+        @big_a.to_s(16)
+      end
+
+      # Given the server's challenge parameters, compute the password claim signature.
+      def compute_claim(user_id:, password:, srp_b:, salt:, secret_block:, timestamp:)
+        big_b = OpenSSL::BN.new(srp_b, 16)
+
+        u = compute_u(big_b)
+        raise AuthenticationError, 'SRP safety check: u must not be zero' if u.zero?
+
+        x = compute_x(salt, user_id, password)
+        s = compute_s(big_b, x, u)
+        hkdf_key = compute_hkdf(s, u)
+
+        secret_block_bytes = Base64.decode64(secret_block)
+        msg = pool_name.encode('utf-8') +
+              user_id.encode('utf-8') +
+              secret_block_bytes +
+              timestamp.encode('utf-8')
+        hmac = OpenSSL::HMAC.digest('SHA256', hkdf_key, msg)
+        Base64.strict_encode64(hmac)
+      end
+
+      private
+
+      def generate_a
+        loop do
+          @small_a = OpenSSL::BN.new(SecureRandom.hex(128), 16)
+          @big_a = @g.mod_exp(@small_a, @n)
+          break unless (@big_a % @n).zero?
+        end
+      end
+
+      def compute_k
+        hex_hash_bn(pad_hex(@n) + pad_hex(@g))
+      end
+
+      def compute_u(big_b)
+        hex_hash_bn(pad_hex(@big_a) + pad_hex(big_b))
+      end
+
+      def compute_x(salt_hex, user_id, password)
+        # Inner: H(poolName || userId || ":" || password) -> hex
+        identity_hex = hex_sha256(pool_name + user_id + ':' + password)
+        # Outer: H(pad(salt) || identityHash)
+        hex_hash_bn(pad_hex_str(salt_hex) + identity_hex)
+      end
+
+      def compute_s(big_b, x, u)
+        gx = @g.mod_exp(x, @n)
+        base = (big_b - @k * gx) % @n
+        exp = @small_a + u * x
+        base.mod_exp(exp, @n)
+      end
+
+      def compute_hkdf(s, u)
+        ikm = hex_to_bytes(pad_hex(s))
+        salt = hex_to_bytes(pad_hex(OpenSSL::BN.new(u.to_s(16), 16)))
+
+        prk = OpenSSL::HMAC.digest('SHA256', salt, ikm)
+        info = INFO_BITS + "\x01"
+        hmac = OpenSSL::HMAC.digest('SHA256', prk, info)
+        hmac[0, 16]
+      end
+
+      # Cognito-style hex padding: ensure even length, prepend 00 if high bit set.
+      # Matches amazon-cognito-identity-js padHex().
+      def pad_hex(bn)
+        pad_hex_str(bn.to_s(16))
+      end
+
+      def pad_hex_str(hex)
+        hex = hex.delete_prefix('-')
+        hex = "0#{hex}" if hex.length.odd?
+        hex = "00#{hex}" if hex[0]&.match?(/[89a-fA-F]/)
+        hex
+      end
+
+      def hex_to_bytes(hex)
+        [hex].pack('H*')
+      end
+
+      # SHA256 of a raw string, returned as hex
+      def hex_sha256(str)
+        OpenSSL::Digest::SHA256.hexdigest(str)
+      end
+
+      # Hash a hex string (converting to bytes first), return as BN
+      def hex_hash_bn(hex_str)
+        digest = OpenSSL::Digest::SHA256.hexdigest(hex_to_bytes(hex_str))
+        OpenSSL::BN.new(digest, 16)
+      end
+    end
+  end
+end

data/lib/alta_labs/client.rb

@@ -0,0 +1,137 @@
+module AltaLabs
+  class Client
+    attr_reader :config, :auth
+
+    def initialize(email: nil, password: nil, config: nil)
+      @config = config || Configuration.new
+      @config.email = email if email
+      @config.password = password if password
+      @auth = Auth::Cognito.new(@config)
+    end
+
+    # Authenticate with Cognito. Called automatically on first request if needed.
+    def authenticate
+      @auth.authenticate
+      self
+    end
+
+    # GET request — token sent as query parameter.
+    def get(path, params = {})
+      ensure_authenticated
+      params[:token] = @auth.id_token
+
+      response = connection.get(path, params)
+      handle_response(response)
+    end
+
+    # POST request — token sent in JSON body.
+    def post(path, body = {})
+      ensure_authenticated
+      body[:token] = @auth.id_token
+
+      response = connection.post(path) do |req|
+        req.body = body.to_json
+      end
+      handle_response(response)
+    end
+
+    # POST request that also includes the Cognito access_token.
+    def post_authenticated(path, body = {})
+      ensure_authenticated
+      body[:token] = @auth.id_token
+      body[:access_token] = @auth.tokens[:access_token]
+
+      response = connection.post(path) do |req|
+        req.body = body.to_json
+      end
+      handle_response(response)
+    end
+
+    def sites
+      @sites ||= Resources::Site.new(self)
+    end
+
+    def devices
+      @devices ||= Resources::Device.new(self)
+    end
+
+    def wifi
+      @wifi ||= Resources::Ssid.new(self)
+    end
+
+    def clients
+      @clients ||= Resources::ClientDevice.new(self)
+    end
+
+    def account
+      @account ||= Resources::Account.new(self)
+    end
+
+    def groups
+      @groups ||= Resources::Group.new(self)
+    end
+
+    def profiles
+      @profiles ||= Resources::Profile.new(self)
+    end
+
+    def floor_plans
+      @floor_plans ||= Resources::FloorPlan.new(self)
+    end
+
+    def filters
+      @filters ||= Resources::Filter.new(self)
+    end
+
+    private
+
+    def ensure_authenticated
+      if @auth.id_token.nil?
+        authenticate
+      elsif @auth.token_expired?
+        @auth.refresh
+      end
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @config.api_url) do |f|
+        f.headers['Content-Type'] = 'application/json'
+        f.headers['Accept'] = 'application/json'
+        f.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                          exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = @config.open_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      body = parse_body(response)
+
+      case response.status
+      when 200..299
+        body
+      when 401
+        @auth.refresh
+        raise AuthenticationError, 'Authentication failed after refresh'
+      when 404
+        raise NotFoundError.new(status: response.status, body: body)
+      when 429
+        raise RateLimitError.new(status: response.status, body: body)
+      when 500..599
+        raise ServerError.new(status: response.status, body: body)
+      else
+        raise ApiError.new("#{body}", status: response.status, body: body)
+      end
+    end
+
+    def parse_body(response)
+      return response.body unless response.body.is_a?(String)
+      return nil if response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+  end
+end

data/lib/alta_labs/configuration.rb

@@ -0,0 +1,40 @@
+module AltaLabs
+  class Configuration
+    COGNITO_USER_POOL_ID = 'us-east-1_4QbA7N3Uy'
+    COGNITO_CLIENT_ID = '24bk8l088t5bf31nuceoqb503q'
+    COGNITO_REGION = 'us-east-1'
+    DEFAULT_API_URL = 'https://manage.alta.inc'
+
+    attr_accessor :email, :password, :api_url,
+                  :user_pool_id, :client_id, :region,
+                  :log_level, :timeout, :open_timeout
+
+    def initialize
+      @email = ENV['ALTA_LABS_EMAIL']
+      @password = ENV['ALTA_LABS_PASSWORD']
+      @api_url = ENV.fetch('ALTA_LABS_API_URL', DEFAULT_API_URL)
+      @user_pool_id = COGNITO_USER_POOL_ID
+      @client_id = COGNITO_CLIENT_ID
+      @region = COGNITO_REGION
+      @log_level = :warn
+      @timeout = 30
+      @open_timeout = 10
+    end
+
+    def pool_name
+      user_pool_id.split('_').last
+    end
+
+    def cognito_endpoint
+      "https://cognito-idp.#{region}.amazonaws.com/"
+    end
+
+    def self.default
+      @default ||= new
+    end
+
+    def self.reset!
+      @default = new
+    end
+  end
+end

data/lib/alta_labs/error.rb

@@ -0,0 +1,30 @@
+module AltaLabs
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+  class TokenExpiredError < AuthenticationError; end
+  class InvalidCredentialsError < AuthenticationError; end
+  class MfaRequiredError < AuthenticationError
+    attr_reader :session, :challenge_name
+
+    def initialize(message = 'MFA verification required', session: nil, challenge_name: nil)
+      @session = session
+      @challenge_name = challenge_name
+      super(message)
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "API error (#{status})")
+    end
+  end
+
+  class NotFoundError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+end

data/lib/alta_labs/resource.rb

@@ -0,0 +1,26 @@
+module AltaLabs
+  class Resource
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # GET request — for read operations.
+    def get(path, params = {})
+      client.get(path, params)
+    end
+
+    # POST request — for write/mutation operations.
+    def post(path, body = {})
+      client.post(path, body)
+    end
+
+    # POST with access_token — for account operations.
+    def post_authenticated(path, body = {})
+      client.post_authenticated(path, body)
+    end
+  end
+end

data/lib/alta_labs/resources/account.rb

@@ -0,0 +1,17 @@
+module AltaLabs
+  module Resources
+    class Account < Resource
+      def info
+        post_authenticated('/api/account/info')
+      end
+
+      def list
+        post_authenticated('/api/account/list')
+      end
+
+      def update(**params)
+        post_authenticated('/api/account/update', params)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/client_device.rb

@@ -0,0 +1,13 @@
+module AltaLabs
+  module Resources
+    class ClientDevice < Resource
+      def edit(id:, **params)
+        post('/api/client/edit', params.merge(id: id))
+      end
+
+      def delete(id:)
+        post('/api/client/delete', id: id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/device.rb

@@ -0,0 +1,41 @@
+module AltaLabs
+  module Resources
+    class Device < Resource
+      def list(site_id:)
+        get('/api/device/list', siteid: site_id)
+      end
+
+      def add(site_id:, **params)
+        post('/api/device/add', params.merge(siteid: site_id))
+      end
+
+      def add_serial(site_id:, serial:, **params)
+        post('/api/device/add-serial', params.merge(siteid: site_id, serial: serial))
+      end
+
+      def edit(id:, **params)
+        post('/api/device/edit', params.merge(id: id))
+      end
+
+      def delete(id:)
+        post('/api/device/delete', id: id)
+      end
+
+      def search(query:, **params)
+        post('/api/device/search', params.merge(query: query))
+      end
+
+      def grab(id:)
+        post('/api/device/grab', id: id)
+      end
+
+      def release(id:)
+        post('/api/device/release', id: id)
+      end
+
+      def move(id:, site_id:)
+        post('/api/device/move', id: id, siteid: site_id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/filter.rb

@@ -0,0 +1,17 @@
+module AltaLabs
+  module Resources
+    class Filter < Resource
+      def get_filter(site_id:)
+        get('/api/filter', siteid: site_id)
+      end
+
+      def set(site_id:, **params)
+        post('/api/filter', params.merge(siteid: site_id))
+      end
+
+      def pause(site_id:, **params)
+        post('/api/filter/pause', params.merge(siteid: site_id))
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/floor_plan.rb

@@ -0,0 +1,25 @@
+module AltaLabs
+  module Resources
+    class FloorPlan < Resource
+      def floors(site_id:)
+        get('/api/floor-plan/floors', siteid: site_id)
+      end
+
+      def create_floor(**params)
+        post('/api/floor-plan/floor', params)
+      end
+
+      def delete_floor(id:)
+        post('/api/floor-plan/delete-floor', id: id)
+      end
+
+      def devices(site_id:)
+        get('/api/floor-plan/devices', siteid: site_id)
+      end
+
+      def walls(site_id:)
+        get('/api/floor-plan/walls', siteid: site_id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/group.rb

@@ -0,0 +1,17 @@
+module AltaLabs
+  module Resources
+    class Group < Resource
+      def add(site_id:, **params)
+        post('/api/group/add', params.merge(siteid: site_id))
+      end
+
+      def edit(id:, **params)
+        post('/api/group/edit', params.merge(id: id))
+      end
+
+      def delete(id:)
+        post('/api/group/delete', id: id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/profile.rb

@@ -0,0 +1,17 @@
+module AltaLabs
+  module Resources
+    class Profile < Resource
+      def list(site_ids: [])
+        post('/api/profile/list', siteids: site_ids)
+      end
+
+      def edit(id:, **params)
+        post('/api/profile/edit', params.merge(id: id))
+      end
+
+      def delete(id:)
+        post('/api/profile/delete', id: id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/site.rb

@@ -0,0 +1,57 @@
+module AltaLabs
+  module Resources
+    class Site < Resource
+      def list(timezone: nil)
+        params = {}
+        params[:tz] = timezone if timezone
+        get('/api/sites/list', params)
+      end
+
+      def find(id:)
+        get('/api/site', id: id)
+      end
+
+      def stats(id:)
+        post('/api/sites/stats', siteid: id)
+      end
+
+      def audit(id:)
+        get('/api/site/audit', id: id)
+      end
+
+      def asn(id:, ip:)
+        get('/api/site/asn', id: id, ip: ip)
+      end
+
+      def create(name:, type: nil, icon: nil, location: nil)
+        params = { name: name }
+        params[:type] = type if type
+        params[:icon] = icon if icon
+        params[:location] = location if location
+        post('/api/sites/new', params)
+      end
+
+      def rename(id:, name:, icon: nil)
+        params = { siteid: id, name: name }
+        params[:icon] = icon if icon
+        post('/api/sites/rename', params)
+      end
+
+      def copy(id:)
+        post('/api/sites/copy', siteid: id)
+      end
+
+      def delete(id:)
+        post('/api/sites/delete', siteid: id)
+      end
+
+      def sync(id:)
+        post('/api/site/sync', siteid: id)
+      end
+
+      def remove_user(id:, user_id:)
+        post('/api/sites/remove-user', siteid: id, userid: user_id)
+      end
+    end
+  end
+end

data/lib/alta_labs/resources/ssid.rb

@@ -0,0 +1,47 @@
+module AltaLabs
+  module Resources
+    class Ssid < Resource
+      def list(site_id:)
+        get('/api/wifi/ssid/list', siteid: site_id)
+      end
+
+      def find(id:)
+        get('/api/wifi/ssid', id: id)
+      end
+
+      def blob(id:)
+        get('/api/wifi/ssid-blob', id: id)
+      end
+
+      def create(**params)
+        post('/api/wifi/ssid', params)
+      end
+
+      def delete(id:)
+        post('/api/wifi/ssid/delete', id: id)
+      end
+
+      def audit(id:)
+        get('/api/wifi/ssid/audit', id: id)
+      end
+
+      def sync_template(site_id:)
+        post('/api/wifi/ssid-template/sync', siteid: site_id)
+      end
+
+      def approve(site_id:, **params)
+        post('/api/wifi/approve', params.merge(siteid: site_id))
+      end
+
+      def auth_respond(site_id:, event_id:, allow:, timeout: nil)
+        params = { siteid: site_id, eventid: event_id, allow: allow }
+        params[:timeout] = timeout if timeout
+        post('/api/wifi/auth-resp', params)
+      end
+
+      def reset_voucher(site_id:, **params)
+        post('/api/wifi/voucher/reset', params.merge(siteid: site_id))
+      end
+    end
+  end
+end

data/lib/alta_labs/version.rb

@@ -0,0 +1,3 @@
+module AltaLabs
+  VERSION = '0.1.0'
+end

data/lib/alta_labs.rb

@@ -0,0 +1,52 @@
+require 'json'
+require 'logger'
+require 'openssl'
+require 'securerandom'
+require 'base64'
+require 'pathname'
+require 'time'
+
+require 'faraday'
+require 'faraday/retry'
+
+require_relative 'alta_labs/version'
+require_relative 'alta_labs/error'
+require_relative 'alta_labs/configuration'
+require_relative 'alta_labs/auth/srp'
+require_relative 'alta_labs/auth/cognito'
+require_relative 'alta_labs/resource'
+require_relative 'alta_labs/resources/account'
+require_relative 'alta_labs/resources/site'
+require_relative 'alta_labs/resources/device'
+require_relative 'alta_labs/resources/ssid'
+require_relative 'alta_labs/resources/client_device'
+require_relative 'alta_labs/resources/group'
+require_relative 'alta_labs/resources/profile'
+require_relative 'alta_labs/resources/floor_plan'
+require_relative 'alta_labs/resources/filter'
+require_relative 'alta_labs/client'
+
+module AltaLabs
+  class << self
+    attr_writer :logger
+
+    def root(*args)
+      (@root ||= Pathname.new(File.expand_path('../', __dir__))).join(*args)
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.progname = name
+        log.level = Logger::WARN
+      end
+    end
+
+    def configure
+      yield(Configuration.default)
+    end
+
+    def configuration
+      Configuration.default
+    end
+  end
+end

metadata

@@ -0,0 +1,195 @@
+--- !ruby/object:Gem::Specification
+name: alta_labs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dale Stevens
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A Ruby client library for interacting with the Alta Labs cloud management
+  platform. Manage sites, devices, WiFi networks, and more programmatically.
+email:
+- dale@twilightcoders.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/alta_labs.rb
+- lib/alta_labs/auth/cognito.rb
+- lib/alta_labs/auth/srp.rb
+- lib/alta_labs/client.rb
+- lib/alta_labs/configuration.rb
+- lib/alta_labs/error.rb
+- lib/alta_labs/resource.rb
+- lib/alta_labs/resources/account.rb
+- lib/alta_labs/resources/client_device.rb
+- lib/alta_labs/resources/device.rb
+- lib/alta_labs/resources/filter.rb
+- lib/alta_labs/resources/floor_plan.rb
+- lib/alta_labs/resources/group.rb
+- lib/alta_labs/resources/profile.rb
+- lib/alta_labs/resources/site.rb
+- lib/alta_labs/resources/ssid.rb
+- lib/alta_labs/version.rb
+homepage: https://github.com/TwilightCoders/alta_labs
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/TwilightCoders/alta_labs
+  source_code_uri: https://github.com/TwilightCoders/alta_labs
+  changelog_uri: https://github.com/TwilightCoders/alta_labs/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/TwilightCoders/alta_labs/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the Alta Labs cloud management API
+test_files: []