licensekit-ruby 0.1.0.alpha.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7393f8b686ec83cf5e6ae56c89b4b77143ea5deba5b4303075a55851e40a55c5
+  data.tar.gz: 813763b1dd7840a3e2cd4b519185bfbac5868615b7df1e3951b7b542992110f1
+SHA512:
+  metadata.gz: f830740d4dcb692b6cce194cfe6aae51b0775f2bc7ed6ea77c6c590db788dc41a47c87c8b5ba9c8a09084eb95ea1f539340a15be6a0fd2b1f5a15346bfbb577a
+  data.tar.gz: 8b74306a0065d0198a56d42a8d9edc8a8c4fd02b6908ed8157bbedda6e3b6b6263baeed3c5b81e1da5b0bd0c3ba26c3218efb4e6c073068aa0ddba431dddfdc8

data/.gitignore

@@ -0,0 +1,4 @@
+/.bundle/
+/pkg/
+/vendor/bundle/
+/*.gem

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Main
+
+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,112 @@
+# `licensekit-ruby`
+
+First-party Ruby SDK for `licensekit.dev`.
+
+It provides Management, Runtime, and System clients for the LicenseKit licensing API, plus least-privilege scope metadata and Ed25519 runtime-signature verification helpers for activation, validation, metering, and offline-aware license flows.
+
+## Why use it
+
+- `LicenseKit::ManagementClient`, `LicenseKit::RuntimeClient`, and `LicenseKit::SystemClient`
+- Runtime signature verification backed by `ed25519`
+- Least-privilege scope discovery derived from the OpenAPI contract
+- Hosted and self-hosted support through a configurable `base_url`
+
+Links:
+
+- [Agent quickstart](https://licensekit.dev/docs/agent-quickstart)
+- [API contract notes](https://licensekit.dev/docs/api-contract)
+- [OpenAPI spec](https://licensekit.dev/openapi.yaml)
+- [LLM reference](https://licensekit.dev/llms.txt)
+- [Source repository](https://github.com/drmain1/licensekit-ruby)
+
+## Install
+
+```bash
+gem install licensekit-ruby
+```
+
+## Quick Start
+
+```ruby
+require "licensekit"
+
+base_url = "https://api.licensekit.dev"
+
+system = LicenseKit::SystemClient.new(base_url: base_url)
+health = system.health
+puts health["data"]["status"]
+
+management = LicenseKit::ManagementClient.new(
+  base_url: base_url,
+  token: "lkm_..."
+)
+
+product = management.create_product(
+  body: {
+    "name" => "Example App",
+    "code" => "example-app"
+  }
+)
+
+runtime = LicenseKit::RuntimeClient.new(
+  base_url: base_url,
+  license_key: "lsk_..."
+)
+
+result = runtime.validate_license(
+  body: {
+    "fingerprint" => "host-123"
+  }
+)
+
+public_keys = system.list_public_keys
+verified = LicenseKit.verify_runtime_result(
+  result,
+  LicenseKit::PublicKeyStore.new(public_keys["data"])
+)
+
+puts [product["data"]["id"], verified.ok].join(" ")
+```
+
+## Package Shape
+
+- `LicenseKit::ManagementClient`
+  Uses `Authorization: Bearer <token>` for `/api/v1/...` management operations.
+- `LicenseKit::RuntimeClient`
+  Uses `Authorization: License <license-key>` for `/api/v1/license/...` runtime operations.
+- `LicenseKit::SystemClient`
+  Unauthenticated access to `/health`, `/healthz`, `/readyz`, `/metrics`, and `/api/v1/system/public-keys`.
+
+Hosted deployments should prefer `/health` for liveness checks behind `api.licensekit.dev`.
+`/healthz` remains available for local and self-hosted compatibility.
+
+## Scope Metadata
+
+```ruby
+required = LicenseKit.get_required_scopes("createProduct")
+allowed = LicenseKit.has_required_scopes("createProduct", ["product:write"])
+```
+
+## Raw Response Access
+
+Each client exposes a `raw` companion for callers that need status codes and headers.
+
+```ruby
+system = LicenseKit::SystemClient.new(base_url: "https://api.licensekit.dev")
+ready = system.raw.readyz
+
+puts [ready.status, ready.data["data"]["status"]].join(" ")
+```
+
+## Development
+
+```bash
+bundle install
+ruby scripts/generate_from_openapi.rb
+ruby -Ilib:test test/test_client.rb
+ruby -Ilib:test test/test_scopes.rb
+ruby -Ilib:test test/test_verification.rb
+gem build licensekit-ruby.gemspec
+```
+
+Generation uses the checked-in OpenAPI snapshot at [`openapi/openapi.yaml`](./openapi/openapi.yaml).

data/examples/01_create_scoped_api_key.rb

@@ -0,0 +1,16 @@
+require "licensekit"
+
+base_url = ENV.fetch("LICENSEKIT_BASE_URL", "https://api.licensekit.dev")
+management = LicenseKit::ManagementClient.new(
+  base_url: base_url,
+  token: ENV.fetch("LICENSEKIT_MANAGEMENT_TOKEN")
+)
+
+response = management.create_api_key(
+  body: {
+    "name" => "product-read",
+    "scopes" => ["product:read"]
+  }
+)
+
+puts response["data"]["api_key"]["name"]

data/examples/02_runtime_validate_and_verify.rb

@@ -0,0 +1,22 @@
+require "licensekit"
+
+base_url = ENV.fetch("LICENSEKIT_BASE_URL", "https://api.licensekit.dev")
+runtime = LicenseKit::RuntimeClient.new(
+  base_url: base_url,
+  license_key: ENV.fetch("LICENSEKIT_LICENSE_KEY")
+)
+system = LicenseKit::SystemClient.new(base_url: base_url)
+
+result = runtime.validate_license(
+  body: {
+    "fingerprint" => ENV.fetch("LICENSEKIT_FINGERPRINT", "host-123")
+  }
+)
+
+public_keys = system.list_public_keys
+verified = LicenseKit.verify_runtime_result(
+  result,
+  LicenseKit::PublicKeyStore.new(public_keys["data"])
+)
+
+puts [result["data"]["status"], verified.ok].join(" ")

data/lib/licensekit/client.rb

@@ -0,0 +1,257 @@
+require "cgi"
+require "date"
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+module LicenseKit
+  class TransportError < StandardError; end
+
+  def self.normalize_base_url(base_url)
+    trimmed = base_url.to_s.strip
+    raise ArgumentError, "base_url is required" if trimmed.empty?
+
+    trimmed.sub(%r{/+\z}, "")
+  end
+
+  class DefaultTransport
+    def call(request)
+      uri = URI.parse(request.url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      if request.timeout
+        http.open_timeout = request.timeout
+        http.read_timeout = request.timeout
+        http.write_timeout = request.timeout if http.respond_to?(:write_timeout=)
+      end
+
+      http_request = request_class(request.method).new(uri.request_uri)
+      request.headers.each do |key, value|
+        http_request[key] = value
+      end
+      http_request.body = request.body unless request.body.nil?
+
+      response = http.request(http_request)
+      TransportResponse.new(
+        status: response.code.to_i,
+        headers: response.each_header.to_h,
+        body: response.body.to_s
+      )
+    rescue StandardError => e
+      raise TransportError, e.message
+    end
+
+    private
+
+    def request_class(method)
+      case method.to_s.upcase
+      when "GET" then Net::HTTP::Get
+      when "POST" then Net::HTTP::Post
+      when "PATCH" then Net::HTTP::Patch
+      when "PUT" then Net::HTTP::Put
+      when "DELETE" then Net::HTTP::Delete
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+  end
+
+  class BaseClient
+    def initialize(base_url:, auth_type:, auth_value:, headers: nil, timeout: nil, user_agent: nil, retry_options: nil, transport: nil)
+      @base_url = LicenseKit.normalize_base_url(base_url)
+      @default_headers = normalize_headers(headers)
+      @timeout = timeout
+      @user_agent = user_agent
+      @auth_type = auth_type
+      @auth_value = auth_value
+      @retry = retry_options || RetryOptions.new
+      @transport = transport || DefaultTransport.new
+    end
+
+    private
+
+    def perform_request(operation_id, request = nil, options: nil, **kwargs)
+      perform_request_raw(operation_id, request, options: options, **kwargs).data
+    end
+
+    def perform_request_raw(operation_id, request = nil, options: nil, **kwargs)
+      metadata = Generated::OPERATION_METADATA.fetch(operation_id)
+      normalized_request = normalize_request(request, kwargs)
+      url = build_url(metadata[:path], normalized_request)
+      headers = build_headers(options, normalized_request)
+      body = nil
+
+      if normalized_request.key?(:body)
+        headers["Content-Type"] = "application/json"
+        body = JSON.generate(normalized_request[:body])
+      end
+
+      transport_request = TransportRequest.new(
+        method: metadata[:method],
+        url: url,
+        headers: headers,
+        body: body,
+        timeout: options&.timeout || @timeout
+      )
+
+      response = send_with_retry(transport_request)
+      success_kind = metadata[:success][response.status]
+      raise ApiError.from_response(response.status, parse_error_body(response)) if success_kind.nil?
+
+      RawResponse.new(
+        status: response.status,
+        headers: response.headers,
+        data: parse_success_body(response, success_kind),
+        response: response,
+        body: response.body
+      )
+    end
+
+    def normalize_request(request, kwargs)
+      merged = {}
+      merged.merge!(request) if request.is_a?(Hash)
+      merged.merge!(kwargs.transform_keys(&:to_sym))
+      merged
+    end
+
+    def build_url(path_template, request)
+      path = path_template.dup
+      path_values = request[:path]
+      if path_values
+        raise TypeError, "request[:path] must be a hash" unless path_values.is_a?(Hash)
+
+        path_values.each do |key, value|
+          escaped = CGI.escape(value.to_s).gsub("+", "%20")
+          path.gsub!("{#{key}}", escaped)
+        end
+      end
+
+      raise ArgumentError, "Missing path parameters for #{path_template}" if path.include?("{") || path.include?("}")
+
+      query_values = request[:query]
+      return "#{@base_url}#{path}" if query_values.nil? || query_values.empty?
+      raise TypeError, "request[:query] must be a hash" unless query_values.is_a?(Hash)
+
+      encoded = URI.encode_www_form(iter_query_params(query_values))
+      "#{@base_url}#{path}?#{encoded}"
+    end
+
+    def iter_query_params(query)
+      query.each_with_object([]) do |(key, value), items|
+        normalize_query_value(key.to_s, value).each { |entry| items << entry }
+      end
+    end
+
+    def normalize_query_value(key, value)
+      case value
+      when nil
+        []
+      when Array
+        value.flat_map { |item| normalize_query_value(key, item) }
+      when Date, DateTime, Time
+        [[key, value.iso8601]]
+      when true
+        [[key, "true"]]
+      when false
+        [[key, "false"]]
+      else
+        [[key, value.to_s]]
+      end
+    end
+
+    def build_headers(options, request)
+      headers = @default_headers.dup
+      headers.merge!(normalize_headers(options.headers)) if options&.headers
+
+      headers["Accept"] ||= "application/json"
+      headers["User-Agent"] ||= @user_agent if @user_agent
+
+      case @auth_type
+      when "bearer"
+        headers["Authorization"] = "Bearer #{@auth_value}" if @auth_value
+      when "license"
+        headers["Authorization"] = "License #{@auth_value}" if @auth_value
+      end
+
+      headers["Idempotency-Key"] = request[:idempotency_key].to_s if request.key?(:idempotency_key)
+      headers
+    end
+
+    def send_with_retry(transport_request)
+      retries = @retry.retries
+      retryable_methods = @retry.retryable_methods
+      should_retry = retryable_methods.include?(transport_request.method.to_s.upcase)
+
+      attempt = 0
+      begin
+        attempt += 1
+        response = @transport.call(transport_request)
+        coerce_transport_response(response)
+      rescue StandardError => e
+        raise e unless should_retry && attempt <= retries
+
+        sleep([0.1 * attempt, 0.5].min)
+        retry
+      end
+    end
+
+    def coerce_transport_response(response)
+      return response if response.is_a?(TransportResponse)
+
+      if response.is_a?(Hash)
+        return TransportResponse.new(
+          status: response.fetch(:status) { response.fetch("status") },
+          headers: response[:headers] || response["headers"] || {},
+          body: response[:body] || response["body"] || ""
+        )
+      end
+
+      if response.respond_to?(:status) && response.respond_to?(:headers) && response.respond_to?(:body)
+        return TransportResponse.new(status: response.status, headers: response.headers, body: response.body)
+      end
+
+      raise TypeError, "transport must return a TransportResponse-compatible object"
+    end
+
+    def parse_success_body(response, kind)
+      case kind
+      when "empty"
+        nil
+      when "text"
+        response.body.to_s
+      else
+        JSON.parse(response.body.to_s)
+      end
+    end
+
+    def parse_error_body(response)
+      content_type = header_value(response.headers, "Content-Type").to_s
+      if content_type.include?("application/json")
+        JSON.parse(response.body.to_s)
+      else
+        response.body.to_s
+      end
+    rescue JSON::ParserError
+      nil
+    end
+
+    def normalize_headers(headers)
+      return {} if headers.nil?
+      raise TypeError, "headers must be a hash" unless headers.is_a?(Hash)
+
+      headers.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value.to_s
+      end
+    end
+
+    def header_value(headers, name)
+      return nil unless headers
+
+      headers.each do |key, value|
+        return value if key.to_s.downcase == name.downcase
+      end
+      nil
+    end
+  end
+end

data/lib/licensekit/errors.rb

@@ -0,0 +1,62 @@
+module LicenseKit
+  class ApiError < StandardError
+    attr_reader :status, :code, :detail, :request_id, :timestamp, :body
+
+    def initialize(status:, code:, message:, detail: nil, request_id: nil, timestamp: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @detail = detail
+      @request_id = request_id
+      @timestamp = timestamp
+      @body = body
+    end
+
+    def self.from_response(status, body)
+      envelope = LicenseKit.parse_error_envelope(body)
+      return new(status: status, code: "UNKNOWN_ERROR", message: "Request failed with status #{status}", body: body) if envelope.nil?
+
+      meta = envelope["meta"] || {}
+      new(
+        status: status,
+        code: envelope["error"]["code"],
+        message: envelope["error"]["message"],
+        detail: envelope["error"]["detail"],
+        request_id: meta["request_id"],
+        timestamp: meta["timestamp"],
+        body: body
+      )
+    end
+  end
+
+  def self.api_error?(value)
+    value.is_a?(ApiError)
+  end
+
+  def self.parse_error_envelope(body)
+    return nil unless body.is_a?(Hash)
+
+    error = body["error"]
+    return nil unless error.is_a?(Hash)
+    return nil unless error["code"].is_a?(String) && error["message"].is_a?(String)
+
+    result = {
+      "error" => {
+        "code" => error["code"],
+        "message" => error["message"]
+      }
+    }
+
+    result["error"]["detail"] = error["detail"] if error["detail"].is_a?(String)
+
+    meta = body["meta"]
+    if meta.is_a?(Hash) && meta["request_id"].is_a?(String) && meta["timestamp"].is_a?(String)
+      result["meta"] = {
+        "request_id" => meta["request_id"],
+        "timestamp" => meta["timestamp"]
+      }
+    end
+
+    result
+  end
+end