scaled 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e7b20aff254a7d3778443bde18004a88fe3f95d9a066a3bc04dc7965099be01
+  data.tar.gz: 9880c240d23f84a6bf64ff40e56de7a40cfe2d8894a4a8d5c81096366c0ab6e4
+SHA512:
+  metadata.gz: f5d23f531c3d6079363f71716064f79e7b17181f4b35c4f4cbac60d85640912e6012a1b76edee9921ee5e5692a36225b4de5a03e288a5c429645754324277c53
+  data.tar.gz: de5e1ecab2b985a02c2a75e61e9ff316ff75031fcf2ce9eccd68d07c31944ae0758e8962a2d91d3da3cb2e42158ebd7426db3505712b3bc5e2db45b0d85a9622

data/.env.example

@@ -0,0 +1,31 @@
+# ============================================================
+# Scaled environment variables / Змінні середовища для Scaled
+# ============================================================
+
+# Enable integration smoke tests:
+# 1 = run integration specs, any other value = skip.
+# Увімкнути інтеграційні smoke-тести:
+# 1 = запускати інтеграційні спеки, будь-яке інше значення = пропускати.
+RUN_INTEGRATION=0
+
+# Tailscale API token for Bearer auth mode.
+# API токен Tailscale для режиму Bearer auth.
+TAILSCALE_API_TOKEN=tskey-api-xxxxxxxxxxxxxxxx
+
+# Tailnet target for API requests.
+# Use "-" to use the token-owned tailnet.
+# Tailnet для API-запитів.
+# Використовуйте "-" для tailnet, що прив'язаний до токена.
+TAILNET=-
+
+# OAuth client ID (client credentials flow).
+# OAuth client ID (режим client credentials).
+TAILSCALE_OAUTH_CLIENT_ID=
+
+# OAuth client secret (client credentials flow).
+# OAuth client secret (режим client credentials).
+TAILSCALE_OAUTH_CLIENT_SECRET=
+
+# Space-separated OAuth scopes.
+# Scopes OAuth через пробіл.
+TAILSCALE_OAUTH_SCOPES=devices:core:read auth_keys:read logs:configuration:read logs:network:read

data/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS Instructions
+
+- All newly added or modified methods must include concise method documentation.
+- Preferred format is YARD-style comments directly above the method.
+- Minimum required doc fields for public/protected methods:
+  - `@param` for non-obvious inputs
+  - `@return` with type/shape
+  - one short behavior note when side effects, defaults, or fallbacks matter
+- Private helper methods may skip full docs only when they are trivial and self-explanatory (for example simple value normalization or key formatting); otherwise document them too.
+- After every code change, add or update automated tests that cover the changed behavior.
+- Method documentation must explicitly describe method parameters (`@param`) for all non-trivial inputs.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Voloshyn Ruslan
+
+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,393 @@
+# Scaled
+
+`Scaled` is a read-only Ruby client for the Tailscale API.
+
+`Scaled` це read-only Ruby клієнт для Tailscale API.
+
+Current scope of the gem:
+- devices inventory (`list`, `get`)
+- keys metadata (`list`, `get`)
+- logs (`configuration`, `network`)
+
+No create/update/delete actions are exposed in resource wrappers.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "scaled"
+```
+
+Or install directly:
+
+```bash
+gem install scaled
+```
+
+## Usage
+
+Environment variables are documented in [.env.example](./.env.example).
+Змінні середовища задокументовані в [.env.example](./.env.example).
+
+### API token auth
+
+```ruby
+require "scaled"
+
+client = Scaled.client(
+  api_token: ENV.fetch("TAILSCALE_API_TOKEN"),
+  tailnet: ENV.fetch("TAILNET", "-")
+)
+
+devices = client.devices.list
+key = client.keys.get("key-id")
+logs = client.logs.configuration(query: { limit: 100 })
+```
+
+### OAuth client credentials auth
+
+```ruby
+require "scaled"
+
+client = Scaled.client(
+  oauth: {
+    client_id: ENV.fetch("TAILSCALE_OAUTH_CLIENT_ID"),
+    client_secret: ENV.fetch("TAILSCALE_OAUTH_CLIENT_SECRET"),
+    scopes: %w[devices:core:read auth_keys:read logs:configuration:read logs:network:read]
+  },
+  tailnet: ENV.fetch("TAILNET", "-")
+)
+
+devices = client.devices.list
+```
+
+Notes:
+- OAuth access tokens are fetched from `https://api.tailscale.com/api/v2/oauth/token`.
+- Tokens are cached and refreshed automatically before expiration.
+
+## Rails integration
+
+### 1. Add gem to Rails app
+
+```ruby
+# Gemfile
+gem "scaled"
+```
+
+```bash
+bundle install
+```
+
+### 2. Configure credentials or env
+
+Store secrets in Rails credentials (recommended) or environment variables.
+
+Example credentials keys:
+
+```yaml
+tailscale:
+  api_token: tskey-api-...
+  tailnet: "-"
+```
+
+For OAuth mode:
+
+```yaml
+tailscale:
+  oauth_client_id: ...
+  oauth_client_secret: ...
+  oauth_scopes: "devices:core:read auth_keys:read logs:configuration:read logs:network:read"
+  tailnet: "-"
+```
+
+### 3. Create initializer
+
+```ruby
+# config/initializers/scaled.rb
+Rails.application.config.x.scaled_client =
+  if Rails.application.credentials.dig(:tailscale, :api_token).present?
+    Scaled.client(
+      api_token: Rails.application.credentials.dig(:tailscale, :api_token),
+      tailnet: Rails.application.credentials.dig(:tailscale, :tailnet) || "-"
+    )
+  else
+    Scaled.client(
+      oauth: {
+        client_id: Rails.application.credentials.dig(:tailscale, :oauth_client_id),
+        client_secret: Rails.application.credentials.dig(:tailscale, :oauth_client_secret),
+        scopes: Rails.application.credentials.dig(:tailscale, :oauth_scopes).to_s.split
+      },
+      tailnet: Rails.application.credentials.dig(:tailscale, :tailnet) || "-"
+    )
+  end
+```
+
+### 4. Add service object
+
+```ruby
+# app/services/tailscale_client.rb
+class TailscaleClient
+  def self.client
+    Rails.configuration.x.scaled_client
+  end
+
+  def self.devices
+    client.devices.list
+  end
+
+  def self.keys
+    client.keys.list
+  end
+
+  def self.configuration_logs(limit: 100)
+    client.logs.configuration(query: { limit: limit })
+  end
+end
+```
+
+### 5. Use in Rails code
+
+```ruby
+# rails console
+TailscaleClient.devices
+TailscaleClient.keys
+```
+
+```ruby
+# app/jobs/sync_tailscale_devices_job.rb
+class SyncTailscaleDevicesJob < ApplicationJob
+  queue_as :default
+
+  def perform
+    devices = TailscaleClient.devices
+    Rails.logger.info("tailscale_devices_count=#{devices.fetch('devices', []).size}")
+  end
+end
+```
+
+Ready-to-copy templates are included:
+- `examples/rails/scaled_initializer.rb`
+- `examples/rails/tailscale_client.rb`
+
+## Gem and curl examples
+
+Examples below do the same read-only operations via gem and `curl`.
+
+### List devices
+
+```ruby
+client = Scaled.client(api_token: ENV.fetch("TAILSCALE_API_TOKEN"), tailnet: "-")
+response = client.devices.list
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/devices"
+```
+
+### Get one device
+
+```ruby
+response = client.devices.get("device-id")
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/device/device-id"
+```
+
+### List keys
+
+```ruby
+response = client.keys.list
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/keys"
+```
+
+### Read configuration logs
+
+```ruby
+response = client.logs.configuration(query: { limit: 100 })
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/logging/configuration?limit=100"
+```
+
+### Read network logs
+
+```ruby
+response = client.logs.network(query: { limit: 100 })
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/logging/network?limit=100"
+```
+
+## Example responses
+
+Response shapes vary by account features and scopes. Examples:
+
+### Devices list (`client.devices.list`)
+
+```json
+{
+  "devices": [
+    {
+      "id": "n123456CNTRL",
+      "name": "macbook-pro.tailnet.ts.net",
+      "addresses": ["100.101.102.103", "fd7a:115c:a1e0::abcd:1234"],
+      "user": "user@example.com",
+      "os": "macOS",
+      "created": "2026-03-12T07:12:30Z",
+      "lastSeen": "2026-03-12T08:25:44Z",
+      "authorized": true
+    }
+  ]
+}
+```
+
+### Keys list (`client.keys.list`)
+
+```json
+{
+  "keys": [
+    {
+      "id": "key_abc123",
+      "description": "CI read-only key",
+      "created": "2026-03-11T09:00:00Z",
+      "expires": "2026-06-09T09:00:00Z",
+      "capabilities": {
+        "devices": {
+          "create": {
+            "reusable": false,
+            "ephemeral": true
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Configuration logs (`client.logs.configuration`)
+
+```json
+{
+  "events": [
+    {
+      "id": "evt_cfg_1",
+      "time": "2026-03-12T08:11:00Z",
+      "actor": "admin@example.com",
+      "type": "policy.updated",
+      "details": {
+        "source": "api"
+      }
+    }
+  ]
+}
+```
+
+### Network logs (`client.logs.network`)
+
+```json
+{
+  "events": [
+    {
+      "id": "evt_net_1",
+      "time": "2026-03-12T08:15:00Z",
+      "srcDeviceId": "n123456CNTRL",
+      "dstDeviceId": "n998877CNTRL",
+      "proto": "tcp",
+      "dstPort": 443,
+      "action": "accept"
+    }
+  ]
+}
+```
+
+## Integration smoke tests
+
+Integration tests are opt-in and run only when `RUN_INTEGRATION=1`.
+
+## Environment variables
+
+Main variables used by the gem and tests:
+- `TAILSCALE_API_TOKEN` - API token for Bearer auth mode.
+- `TAILSCALE_OAUTH_CLIENT_ID` - OAuth client ID for client credentials flow.
+- `TAILSCALE_OAUTH_CLIENT_SECRET` - OAuth client secret for client credentials flow.
+- `TAILSCALE_OAUTH_SCOPES` - space-separated OAuth scopes.
+- `TAILNET` - target tailnet (`-` means token-owned tailnet).
+- `RUN_INTEGRATION` - enables/disables integration smoke specs.
+
+See full descriptions and defaults in [.env.example](./.env.example).
+
+### API token smoke
+
+```bash
+RUN_INTEGRATION=1 \
+TAILSCALE_API_TOKEN=tskey-api-... \
+TAILNET=- \
+bundle exec rspec spec/integration/read_only_smoke_spec.rb
+```
+
+### OAuth smoke
+
+```bash
+RUN_INTEGRATION=1 \
+TAILSCALE_OAUTH_CLIENT_ID=... \
+TAILSCALE_OAUTH_CLIENT_SECRET=... \
+TAILSCALE_OAUTH_SCOPES='devices:core:read auth_keys:read logs:configuration:read logs:network:read' \
+TAILNET=- \
+bundle exec rspec spec/integration/read_only_smoke_spec.rb
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## GitHub push and gem release
+
+### Push to GitHub
+
+```bash
+git init
+git add .
+git commit -m "Initial read-only Tailscale client"
+git remote add origin <YOUR_GITHUB_REPO_URL>
+git push -u origin master
+```
+
+### Publish to RubyGems
+
+Before release:
+- update `scaled.gemspec` (`summary`, `description`, `homepage`, `source_code_uri`)
+- update version in `lib/scaled/version.rb`
+- ensure `bundle exec rspec` and `bundle exec rubocop` are green
+- configure RubyGems credentials and MFA
+
+Release:
+
+```bash
+bundle exec rake build
+bundle exec rake release
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/rails/scaled_initializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Example initializer for Rails apps.
+# Приклад ініціалізатора для Rails-застосунків.
+Rails.application.config.x.scaled_client =
+  if Rails.application.credentials.dig(:tailscale, :api_token).present?
+    Scaled.client(
+      api_token: Rails.application.credentials.dig(:tailscale, :api_token),
+      tailnet: Rails.application.credentials.dig(:tailscale, :tailnet) || "-"
+    )
+  else
+    Scaled.client(
+      oauth: {
+        client_id: Rails.application.credentials.dig(:tailscale, :oauth_client_id),
+        client_secret: Rails.application.credentials.dig(:tailscale, :oauth_client_secret),
+        scopes: Rails.application.credentials.dig(:tailscale, :oauth_scopes).to_s.split
+      },
+      tailnet: Rails.application.credentials.dig(:tailscale, :tailnet) || "-"
+    )
+  end

data/examples/rails/tailscale_client.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Rails service wrapper for read-only Tailscale operations.
+# Rails сервіс-обгортка для read-only операцій Tailscale.
+class TailscaleClient
+  class << self
+    # @return [Scaled::Client]
+    # Note: uses client configured in Rails initializer.
+    # Нотатка: використовує клієнт, налаштований в Rails ініціалізаторі.
+    def client
+      Rails.configuration.x.scaled_client
+    end
+
+    # @param query [Hash, nil] optional API query parameters
+    # @return [Hash, Array, nil] devices payload
+    def devices(query: nil)
+      client.devices.list(query: query)
+    rescue Scaled::Error => e
+      handle_error("devices.list", e)
+    end
+
+    # @param key_id [String] key identifier
+    # @return [Hash, Array, nil] key payload
+    def key(key_id)
+      client.keys.get(key_id)
+    rescue Scaled::Error => e
+      handle_error("keys.get", e)
+    end
+
+    # @param query [Hash, nil] optional API query parameters
+    # @return [Hash, Array, nil] keys payload
+    def keys(query: nil)
+      client.keys.list(query: query)
+    rescue Scaled::Error => e
+      handle_error("keys.list", e)
+    end
+
+    # @param limit [Integer] max items from logs endpoint
+    # @return [Hash, Array, nil] configuration logs payload
+    def configuration_logs(limit: 100)
+      client.logs.configuration(query: { limit: limit })
+    rescue Scaled::Error => e
+      handle_error("logs.configuration", e)
+    end
+
+    # @param limit [Integer] max items from logs endpoint
+    # @return [Hash, Array, nil] network logs payload
+    def network_logs(limit: 100)
+      client.logs.network(query: { limit: limit })
+    rescue Scaled::Error => e
+      handle_error("logs.network", e)
+    end
+
+    private
+
+    # @param operation [String] logical operation name
+    # @param error [Scaled::Error] normalized SDK error
+    # @return [void]
+    # Note: logs structured metadata and re-raises for caller-level handling.
+    # Нотатка: логує структуровані метадані та повторно піднімає помилку для caller-рівня.
+    def handle_error(operation, error)
+      Rails.logger.error(
+        {
+          event: "tailscale_api_error",
+          operation: operation,
+          message: error.message,
+          status: error.status,
+          request_id: error.request_id
+        }.to_json
+      )
+      raise
+    end
+  end
+end

data/lib/scaled/auth/api_token.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Auth
+    # API token authentication strategy.
+    # Стратегія автентифікації через API токен.
+    class ApiToken
+      # @param token [String] Tailscale API access token
+      # @return [void]
+      # Note: token is normalized with `strip` to reduce accidental whitespace issues.
+      # Нотатка: токен нормалізується через `strip`, щоб уникнути проблем з пробілами.
+      def initialize(token)
+        normalized = token.to_s.strip
+        raise ArgumentError, "api token must be provided" if normalized.empty?
+
+        @token = normalized
+      end
+
+      # @param headers [Hash{String => String}] mutable request headers
+      # @return [Hash{String => String}] same headers hash with Authorization included
+      # Note: mutates and returns the same hash to avoid unnecessary allocations.
+      # Нотатка: змінює і повертає той самий hash для уникнення зайвих алокацій.
+      def apply(headers)
+        headers["Authorization"] = "Bearer #{@token}"
+        headers
+      end
+    end
+  end
+end

data/lib/scaled/auth/oauth_client_credentials.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Scaled
+  module Auth
+    # OAuth Client Credentials authentication strategy.
+    # Стратегія OAuth Client Credentials для автентифікації.
+    class OAuthClientCredentials
+      DEFAULT_TOKEN_URL = "https://api.tailscale.com/api/v2/oauth/token"
+      REFRESH_SAFETY_WINDOW = 30
+
+      # @param client_id [String] OAuth client identifier
+      # @param client_secret [String] OAuth client secret
+      # @param options [Hash] optional settings (:scopes, :token_url, :open_timeout, :read_timeout, :now)
+      # @return [void]
+      # Note: token refresh is automatic when expiry approaches.
+      # Нотатка: токен оновлюється автоматично при наближенні до завершення дії.
+      def initialize(client_id:, client_secret:, **options)
+        @client_id = normalize_required(client_id, "client_id")
+        @client_secret = normalize_required(client_secret, "client_secret")
+        @scopes = Array(options.fetch(:scopes, [])).map(&:to_s).map(&:strip).reject(&:empty?)
+        @token_url = options.fetch(:token_url, DEFAULT_TOKEN_URL)
+        @open_timeout = options.fetch(:open_timeout, 5)
+        @read_timeout = options.fetch(:read_timeout, 30)
+        @now = options.fetch(:now, -> { Time.now })
+        @token_data = nil
+      end
+
+      # @param headers [Hash{String => String}] mutable request headers
+      # @return [Hash{String => String}] same hash with Bearer authorization
+      # Note: mutates and returns the same hash for compatibility with HTTP layer.
+      # Нотатка: змінює і повертає той самий hash для сумісності з HTTP-шаром.
+      def apply(headers)
+        headers["Authorization"] = "Bearer #{access_token}"
+        headers
+      end
+
+      private
+
+      # @return [String]
+      def access_token
+        refresh_token! if token_missing_or_expiring?
+        @token_data.fetch(:access_token)
+      end
+
+      # @return [Boolean]
+      def token_missing_or_expiring?
+        return true if @token_data.nil?
+
+        @token_data[:expires_at] <= (@now.call + REFRESH_SAFETY_WINDOW)
+      end
+
+      # @return [void]
+      def refresh_token!
+        parsed = parse_token_response(fetch_token_response)
+        @token_data = {
+          access_token: parsed.fetch("access_token"),
+          expires_at: @now.call + parsed.fetch("expires_in").to_i
+        }
+      end
+
+      # @return [Net::HTTPResponse]
+      def fetch_token_response
+        uri = URI(@token_url)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: @open_timeout,
+          read_timeout: @read_timeout
+        ) { |http| http.request(build_token_request(uri)) }
+      end
+
+      # @param uri [URI::Generic]
+      # @return [Net::HTTP::Post]
+      def build_token_request(uri)
+        request = Net::HTTP::Post.new(uri)
+        request.basic_auth(@client_id, @client_secret)
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request["Accept"] = "application/json"
+        request.body = URI.encode_www_form(token_request_body)
+        request
+      end
+
+      # @return [Hash{String => String}]
+      def token_request_body
+        body = { "grant_type" => "client_credentials" }
+        body["scope"] = @scopes.join(" ") unless @scopes.empty?
+        body
+      end
+
+      # @param response [Net::HTTPResponse]
+      # @return [Hash]
+      def parse_token_response(response)
+        status = response.code.to_i
+        parsed = parse_json(response.body)
+        return parsed if status.between?(200, 299)
+
+        message = parsed["error_description"] || parsed["error"] || "oauth token request failed with status #{status}"
+        raise AuthenticationError.new(message, status: status, response_body: parsed)
+      end
+
+      # @param raw_body [String, nil]
+      # @return [Hash]
+      def parse_json(raw_body)
+        return {} if raw_body.nil? || raw_body.strip.empty?
+
+        value = JSON.parse(raw_body)
+        return value if value.is_a?(Hash)
+
+        raise AuthenticationError, "oauth token endpoint returned non-object JSON"
+      rescue JSON::ParserError
+        raise AuthenticationError, "oauth token endpoint returned invalid JSON"
+      end
+
+      # @param value [String]
+      # @param field [String]
+      # @return [String]
+      def normalize_required(value, field)
+        normalized = value.to_s.strip
+        raise ArgumentError, "#{field} must be provided" if normalized.empty?
+
+        normalized
+      end
+    end
+  end
+end

data/lib/scaled/client.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "auth/api_token"
+require_relative "auth/oauth_client_credentials"
+require_relative "http"
+require_relative "resources/devices"
+require_relative "resources/keys"
+require_relative "resources/logs"
+
+module Scaled
+  # Main entry point for interacting with Tailscale API.
+  # Основна точка входу для взаємодії з Tailscale API.
+  class Client
+    attr_reader :tailnet
+
+    # @param api_token [String, nil] Tailscale API token for Bearer auth
+    # @param auth [#apply, nil] custom authentication strategy
+    # @param oauth [Hash, nil] OAuth settings (:client_id, :client_secret, optional :scopes, :token_url)
+    # @param tailnet [String] tailnet name, or "-" for token-owned tailnet
+    # @param http_options [Hash] custom HTTP options (base_url, timeouts, user_agent)
+    # @return [void]
+    # Note: exactly one auth mode must be provided: `api_token`, `auth`, or `oauth`.
+    # Нотатка: потрібно передати рівно один режим auth: `api_token`, `auth` або `oauth`.
+    def initialize(api_token: nil, auth: nil, oauth: nil, tailnet: "-", **http_options)
+      @tailnet = tailnet
+      auth_strategy = resolve_auth(api_token: api_token, auth: auth, oauth: oauth)
+      @http = HTTP.new(auth: auth_strategy, **http_options)
+    end
+
+    # @param path [String] endpoint path
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, Array, String, nil] parsed response body
+    # Note: use this low-level method until resource-specific clients are introduced.
+    # Нотатка: використовуйте цей low-level метод, доки не додані ресурсні клієнти.
+    def get(path, query: nil)
+      @http.request(method: :get, path: path, query: query)
+    end
+
+    # @param path [String] endpoint path
+    # @param body [Hash, Array, nil] JSON body
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, Array, String, nil] parsed response body
+    def post(path, body: nil, query: nil)
+      @http.request(method: :post, path: path, body: body, query: query)
+    end
+
+    # @param path [String] endpoint path
+    # @param body [Hash, Array, nil] JSON body
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, Array, String, nil] parsed response body
+    def put(path, body: nil, query: nil)
+      @http.request(method: :put, path: path, body: body, query: query)
+    end
+
+    # @param path [String] endpoint path
+    # @param body [Hash, Array, nil] JSON body
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, Array, String, nil] parsed response body
+    def patch(path, body: nil, query: nil)
+      @http.request(method: :patch, path: path, body: body, query: query)
+    end
+
+    # @param path [String] endpoint path
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, Array, String, nil] parsed response body
+    def delete(path, query: nil)
+      @http.request(method: :delete, path: path, query: query)
+    end
+
+    # @return [Scaled::Resources::Devices]
+    def devices
+      @devices ||= Resources::Devices.new(self)
+    end
+
+    # @return [Scaled::Resources::Keys]
+    def keys
+      @keys ||= Resources::Keys.new(self)
+    end
+
+    # @return [Scaled::Resources::Logs]
+    def logs
+      @logs ||= Resources::Logs.new(self)
+    end
+
+    private
+
+    # @param api_token [String, nil]
+    # @param auth [#apply, nil]
+    # @param oauth [Hash, nil]
+    # @return [#apply]
+    def resolve_auth(api_token:, auth:, oauth:)
+      present_modes = [!api_token.nil?, !auth.nil?, !oauth.nil?].count(true)
+      raise ArgumentError, "provide exactly one of api_token, auth, or oauth" unless present_modes == 1
+
+      return auth if auth
+      return Auth::ApiToken.new(api_token) if api_token
+
+      build_oauth_auth(oauth)
+    end
+
+    # @param oauth [Hash]
+    # @return [Scaled::Auth::OAuthClientCredentials]
+    def build_oauth_auth(oauth)
+      config = oauth.transform_keys(&:to_sym)
+      Auth::OAuthClientCredentials.new(
+        client_id: config.fetch(:client_id),
+        client_secret: config.fetch(:client_secret),
+        scopes: config.fetch(:scopes, []),
+        token_url: config.fetch(:token_url, Auth::OAuthClientCredentials::DEFAULT_TOKEN_URL)
+      )
+    end
+  end
+end

data/lib/scaled/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Scaled
+  # Base error for all library-level failures.
+  # Базова помилка для всіх помилок бібліотеки.
+  class Error < StandardError
+    attr_reader :status, :response_body, :request_id
+
+    # @param message [String] human-readable error message
+    # @param status [Integer, nil] HTTP status code when available
+    # @param response_body [Hash, String, nil] parsed API error body
+    # @param request_id [String, nil] request identifier from response headers
+    # @return [void]
+    # Note: keeps transport metadata to simplify diagnostics.
+    # Нотатка: зберігає метадані запиту для зручної діагностики.
+    def initialize(message, status: nil, response_body: nil, request_id: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+      @request_id = request_id
+    end
+  end
+
+  # Raised when credentials are missing, invalid, or expired.
+  # Викликається, коли облікові дані відсутні, невалідні або протерміновані.
+  class AuthenticationError < Error; end
+
+  # Raised when authenticated identity lacks required scope/permissions.
+  # Викликається, коли автентифікований суб'єкт не має потрібних прав/скоупів.
+  class AuthorizationError < Error; end
+
+  # Raised when requested resource does not exist.
+  # Викликається, коли запитаний ресурс не існує.
+  class NotFoundError < Error; end
+
+  # Raised when API rate limits the client.
+  # Викликається, коли API обмежує частоту запитів клієнта.
+  class RateLimitError < Error; end
+
+  # Raised when request payload or query is invalid.
+  # Викликається, коли payload або query некоректні.
+  class ValidationError < Error; end
+
+  # Raised for unexpected 5xx responses.
+  # Викликається для неочікуваних відповідей 5xx.
+  class ServerError < Error; end
+end

data/lib/scaled/http.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Scaled
+  # Low-level HTTP wrapper for Tailscale API requests.
+  # Низькорівневий HTTP-обгортка для запитів до Tailscale API.
+  class HTTP
+    DEFAULT_BASE_URL = "https://api.tailscale.com/api/v2"
+
+    # @param auth [#apply] authentication strategy object
+    # @param base_url [String] API base URL
+    # @param open_timeout [Numeric] connection timeout seconds
+    # @param read_timeout [Numeric] read timeout seconds
+    # @param user_agent [String] value for User-Agent header
+    # @return [void]
+    # Note: `auth` must respond to `apply(headers)`.
+    # Нотатка: `auth` має підтримувати метод `apply(headers)`.
+    def initialize(auth:, base_url: DEFAULT_BASE_URL, open_timeout: 5, read_timeout: 30, user_agent: "scaled-ruby")
+      @auth = auth
+      @base_url = base_url
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @user_agent = user_agent
+    end
+
+    # @param method [Symbol, String] HTTP method (:get, :post, ...)
+    # @param path [String] endpoint path beginning with /
+    # @param query [Hash, nil] query params (nil values are dropped)
+    # @param body [Hash, Array, nil] JSON-serializable request body
+    # @param headers [Hash{String => String}] extra request headers
+    # @return [Hash, Array, String, nil] parsed response body
+    # Note: raises specialized Scaled errors for non-2xx responses.
+    # Нотатка: для не-2xx відповідей піднімає спеціалізовані помилки Scaled.
+    def request(method:, path:, query: nil, body: nil, headers: {})
+      uri = build_uri(path, query)
+      http_response = perform_request(method: method, uri: uri, body: body, headers: headers)
+      parse_or_raise(http_response)
+    end
+
+    private
+
+    # @param path [String]
+    # @param query [Hash, nil]
+    # @return [URI::HTTPS, URI::HTTP]
+    def build_uri(path, query)
+      base = URI.join("#{@base_url}/", path.sub(%r{^/}, ""))
+      return base if query.nil? || query.empty?
+
+      compacted = query.each_with_object({}) do |(key, value), memo|
+        memo[key] = value unless value.nil?
+      end
+      base.query = URI.encode_www_form(compacted)
+      base
+    end
+
+    # @param method [Symbol, String]
+    # @param uri [URI::Generic]
+    # @param body [Hash, Array, nil]
+    # @param headers [Hash{String => String}]
+    # @return [Net::HTTPRequest]
+    def build_request(method, uri, body, headers)
+      request = request_class_for(method).new(uri)
+      apply_headers(request, headers)
+      apply_body(request, body)
+      request
+    end
+
+    # @param method [Symbol, String]
+    # @param uri [URI::Generic]
+    # @param body [Hash, Array, nil]
+    # @param headers [Hash{String => String}]
+    # @return [Net::HTTPResponse]
+    def perform_request(method:, uri:, body:, headers:)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) do |http|
+        request = build_request(method, uri, body, headers)
+        http.request(request)
+      end
+    end
+
+    # @param response [Net::HTTPResponse]
+    # @return [Hash, Array, String, nil]
+    def parse_or_raise(response)
+      parsed_body = parse_body(response.body)
+      return parsed_body if success_status?(response.code)
+
+      raise map_error(response, parsed_body)
+    end
+
+    # @param request [Net::HTTPRequest]
+    # @param headers [Hash{String => String}]
+    # @return [void]
+    def apply_headers(request, headers)
+      merged_headers = {
+        "Accept" => "application/json",
+        "User-Agent" => @user_agent
+      }.merge(headers)
+      @auth.apply(merged_headers)
+      merged_headers.each { |key, value| request[key] = value }
+    end
+
+    # @param request [Net::HTTPRequest]
+    # @param body [Hash, Array, nil]
+    # @return [void]
+    def apply_body(request, body)
+      return if body.nil?
+
+      request["Content-Type"] ||= "application/json"
+      request.body = JSON.generate(body)
+    end
+
+    # @param method [Symbol, String]
+    # @return [Class]
+    def request_class_for(method)
+      case method.to_s.downcase
+      when "get" then Net::HTTP::Get
+      when "post" then Net::HTTP::Post
+      when "put" then Net::HTTP::Put
+      when "patch" then Net::HTTP::Patch
+      when "delete" then Net::HTTP::Delete
+      else
+        raise ArgumentError, "unsupported HTTP method: #{method}"
+      end
+    end
+
+    # @param code [String]
+    # @return [Boolean]
+    def success_status?(code)
+      code.to_i.between?(200, 299)
+    end
+
+    # @param raw_body [String, nil]
+    # @return [Hash, Array, String, nil]
+    def parse_body(raw_body)
+      return nil if raw_body.nil? || raw_body.strip.empty?
+
+      JSON.parse(raw_body)
+    rescue JSON::ParserError
+      raw_body
+    end
+
+    # @param response [Net::HTTPResponse]
+    # @param parsed_body [Hash, Array, String, nil]
+    # @return [Scaled::Error]
+    def map_error(response, parsed_body)
+      status = response.code.to_i
+      message = error_message_for(status, parsed_body)
+      request_id = response["x-request-id"]
+
+      error_class_for(status).new(
+        message,
+        status: status,
+        response_body: parsed_body,
+        request_id: request_id
+      )
+    end
+
+    # @param status [Integer]
+    # @return [Class]
+    def error_class_for(status)
+      case status
+      when 400, 422 then ValidationError
+      when 401 then AuthenticationError
+      when 403 then AuthorizationError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else Error
+      end
+    end
+
+    # @param status [Integer]
+    # @param parsed_body [Hash, Array, String, nil]
+    # @return [String]
+    def error_message_for(status, parsed_body)
+      return "HTTP #{status}" unless parsed_body.is_a?(Hash)
+
+      parsed_body["message"] || parsed_body["error"] || "HTTP #{status}"
+    end
+  end
+end

data/lib/scaled/resources/devices.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Resources
+    # API wrapper for tailnet devices.
+    # API-обгортка для комп'ютерів (devices) tailnet.
+    class Devices
+      # @param client [Scaled::Client] configured API client
+      # @return [void]
+      def initialize(client)
+        @client = client
+      end
+
+      # @param query [Hash, nil] optional query params for list endpoint
+      # @return [Hash, Array, String, nil] parsed response
+      # Note: uses current client tailnet scope.
+      # Нотатка: використовує поточний tailnet з client-конфігурації.
+      def list(query: nil)
+        @client.get("/tailnet/#{@client.tailnet}/devices", query: query)
+      end
+
+      # @param device_id [String] Tailscale device identifier
+      # @return [Hash, Array, String, nil] parsed response
+      def get(device_id)
+        @client.get("/device/#{device_id}")
+      end
+    end
+  end
+end

data/lib/scaled/resources/keys.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Resources
+    # API wrapper for tailnet keys metadata.
+    # API-обгортка для метаданих ключів tailnet.
+    class Keys
+      # @param client [Scaled::Client] configured API client
+      # @return [void]
+      def initialize(client)
+        @client = client
+      end
+
+      # @param query [Hash, nil] optional query params
+      # @return [Hash, Array, String, nil] parsed response
+      # Note: returns all visible key records for current scope.
+      # Нотатка: повертає всі доступні записи ключів у поточному scope.
+      def list(query: nil)
+        @client.get("/tailnet/#{@client.tailnet}/keys", query: query)
+      end
+
+      # @param key_id [String] Tailscale key identifier
+      # @return [Hash, Array, String, nil] parsed response
+      def get(key_id)
+        @client.get("/tailnet/#{@client.tailnet}/keys/#{key_id}")
+      end
+    end
+  end
+end

data/lib/scaled/resources/logs.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Resources
+    # API wrapper for tailnet logging endpoints.
+    # API-обгортка для endpoint-ів логування tailnet.
+    class Logs
+      # @param client [Scaled::Client] configured API client
+      # @return [void]
+      def initialize(client)
+        @client = client
+      end
+
+      # @param query [Hash, nil] optional query params
+      # @return [Hash, Array, String, nil] parsed response
+      # Note: retrieves logging configuration events.
+      # Нотатка: повертає події/конфігурацію логування.
+      def configuration(query: nil)
+        @client.get("/tailnet/#{@client.tailnet}/logging/configuration", query: query)
+      end
+
+      # @param query [Hash, nil] optional query params
+      # @return [Hash, Array, String, nil] parsed response
+      # Note: retrieves network log stream snapshots/events.
+      # Нотатка: повертає мережеві логи/події.
+      def network(query: nil)
+        @client.get("/tailnet/#{@client.tailnet}/logging/network", query: query)
+      end
+    end
+  end
+end

data/lib/scaled/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Scaled
+  VERSION = "0.1.1"
+end

data/lib/scaled.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "scaled/version"
+require_relative "scaled/errors"
+require_relative "scaled/client"
+
+# Public namespace for the Scaled gem.
+# Публічний простір імен для gem Scaled.
+module Scaled
+  # Build a configured API client instance.
+  # Створює налаштований екземпляр API клієнта.
+  # @param kwargs [Hash] forwarded options for Scaled::Client
+  # @return [Scaled::Client]
+  def self.client(**)
+    Client.new(**)
+  end
+end

data/sig/scaled.rbs

@@ -0,0 +1,63 @@
+module Scaled
+  VERSION: String
+
+  def self.client: (**untyped kwargs) -> Client
+
+  class Error < StandardError
+    attr_reader status: Integer?
+    attr_reader response_body: Hash[String, untyped] | String | nil
+    attr_reader request_id: String?
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class AuthorizationError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class RateLimitError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  class ServerError < Error
+  end
+
+  class Client
+    attr_reader tailnet: String
+
+    def initialize: (?api_token: String?, ?auth: untyped, ?oauth: Hash[Symbol, untyped]?, ?tailnet: String, **untyped http_options) -> void
+    def get: (String path, ?query: Hash[Symbol | String, untyped]?) -> untyped
+    def post: (String path, ?body: untyped, ?query: Hash[Symbol | String, untyped]?) -> untyped
+    def put: (String path, ?body: untyped, ?query: Hash[Symbol | String, untyped]?) -> untyped
+    def patch: (String path, ?body: untyped, ?query: Hash[Symbol | String, untyped]?) -> untyped
+    def delete: (String path, ?query: Hash[Symbol | String, untyped]?) -> untyped
+    def devices: () -> Resources::Devices
+    def keys: () -> Resources::Keys
+    def logs: () -> Resources::Logs
+  end
+
+  module Resources
+    class Devices
+      def initialize: (Client client) -> void
+      def list: (?query: Hash[Symbol | String, untyped]?) -> untyped
+      def get: (String device_id) -> untyped
+    end
+
+    class Keys
+      def initialize: (Client client) -> void
+      def list: (?query: Hash[Symbol | String, untyped]?) -> untyped
+      def get: (String key_id) -> untyped
+    end
+
+    class Logs
+      def initialize: (Client client) -> void
+      def configuration: (?query: Hash[Symbol | String, untyped]?) -> untyped
+      def network: (?query: Hash[Symbol | String, untyped]?) -> untyped
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: scaled
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Voloshyn Ruslan
+bindir: exe
+cert_chain: []
+date: 2026-03-12 00:00:00.000000000 Z
+dependencies: []
+description: 'Scaled provides a read-only Ruby SDK for Tailscale API endpoints: devices,
+  keys, and logs. Supports API token and OAuth client credentials authentication.'
+email:
+- rebisall@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- AGENTS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/rails/scaled_initializer.rb
+- examples/rails/tailscale_client.rb
+- lib/scaled.rb
+- lib/scaled/auth/api_token.rb
+- lib/scaled/auth/oauth_client_credentials.rb
+- lib/scaled/client.rb
+- lib/scaled/errors.rb
+- lib/scaled/http.rb
+- lib/scaled/resources/devices.rb
+- lib/scaled/resources/keys.rb
+- lib/scaled/resources/logs.rb
+- lib/scaled/version.rb
+- sig/scaled.rbs
+homepage: https://github.com/bublik/scaled
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/bublik/scaled
+  source_code_uri: https://github.com/bublik/scaled
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Read-only Ruby client for Tailscale API
+test_files: []