licensekit-ruby 0.1.0.alpha.0

data/scripts/generate_from_openapi.rb

@@ -0,0 +1,294 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+ROOT = File.expand_path("..", __dir__)
+SPEC_PATH = File.join(ROOT, "openapi", "openapi.yaml")
+GENERATED_DIR = File.join(ROOT, "lib", "licensekit", "generated")
+
+def infer_auth(security)
+  return "none" unless security.is_a?(Array) && !security.empty?
+
+  security.each do |entry|
+    next unless entry.is_a?(Hash)
+    return "bearer" if entry.key?("bearerAuth")
+    return "license" if entry.key?("licenseAuth")
+  end
+
+  "none"
+end
+
+def response_kind(response)
+  return "empty" unless response.is_a?(Hash)
+
+  content = response["content"]
+  return "empty" unless content.is_a?(Hash)
+  return "json" if content.key?("application/json")
+  return "text" if content.key?("text/plain")
+
+  "empty"
+end
+
+def error_response?(response)
+  return false unless response.is_a?(Hash)
+  return true if response["$ref"].is_a?(String)
+
+  schema = response.dig("content", "application/json", "schema")
+  schema.is_a?(Hash) && schema["$ref"] == "#/components/schemas/ErrorEnvelope"
+end
+
+def extract_success_responses(responses)
+  entries = []
+  return entries unless responses.is_a?(Hash)
+
+  responses.each do |raw_status, response|
+    status = Integer(raw_status, exception: false)
+    next if status.nil?
+
+    kind = response_kind(response)
+    if status >= 200 && status < 300
+      entries << [status, kind]
+      next
+    end
+
+    next if error_response?(response)
+
+    entries << [status, kind]
+  end
+
+  raise "operation is missing a successful response" if entries.empty?
+
+  entries.sort_by(&:first)
+end
+
+def camel_to_snake(value)
+  value.gsub(/(.)([A-Z][a-z]+)/, '\1_\2').gsub(/([a-z0-9])([A-Z])/, '\1_\2').downcase
+end
+
+def render_metadata(entries, surfaces)
+  lines = [
+    "# Generated by scripts/generate_from_openapi.rb. Do not edit manually.",
+    "",
+    "module LicenseKit",
+    "  module Generated",
+    "    OPERATION_METADATA = {"
+  ]
+
+  entries.each do |entry|
+    success_pairs = entry[:success].map { |status, kind| "#{status} => #{kind.inspect}" }.join(", ")
+    lines.concat(
+      [
+        "      #{entry[:operation_id].inspect} => {",
+        "        method: #{entry[:method].inspect},",
+        "        path: #{entry[:path].inspect},",
+        "        auth: #{entry[:auth].inspect},",
+        "        summary: #{entry[:summary].inspect},",
+        "        success: { #{success_pairs} }",
+        "      },"
+      ]
+    )
+  end
+
+  lines.concat(
+    [
+      "    }.freeze",
+      "    MANAGEMENT_OPERATION_IDS = #{surfaces.fetch("management").map { |entry| entry[:operation_id] }.inspect}.freeze",
+      "    RUNTIME_OPERATION_IDS = #{surfaces.fetch("runtime").map { |entry| entry[:operation_id] }.inspect}.freeze",
+      "    SYSTEM_OPERATION_IDS = #{surfaces.fetch("system").map { |entry| entry[:operation_id] }.inspect}.freeze",
+      "  end",
+      "end",
+      ""
+    ]
+  )
+  lines.join("\n")
+end
+
+def render_scopes(entries)
+  scopes = entries.flat_map { |entry| entry[:scopes] }.uniq.sort
+  lines = [
+    "# Generated by scripts/generate_from_openapi.rb. Do not edit manually.",
+    "",
+    "module LicenseKit",
+    "  module Generated",
+    "    OPERATION_SCOPES = {"
+  ]
+
+  entries.each do |entry|
+    lines.concat(
+      [
+        "      #{entry[:operation_id].inspect} => {",
+        "        method: #{entry[:method].inspect},",
+        "        path: #{entry[:path].inspect},",
+        "        scopes: #{entry[:scopes].inspect}.freeze",
+        "      },"
+      ]
+    )
+  end
+
+  lines.concat(
+    [
+      "    }.freeze",
+      "    MANAGEMENT_SCOPES = #{scopes.inspect}.freeze",
+      "  end",
+      "end",
+      ""
+    ]
+  )
+  lines.join("\n")
+end
+
+def render_surface_raw(class_name, entries)
+  lines = [
+    "  class #{class_name}",
+    "    def initialize(client)",
+    "      @client = client",
+    "    end",
+    ""
+  ]
+
+  entries.each do |entry|
+    lines.concat(
+      [
+        "    # #{entry[:summary]}",
+        "    def #{entry[:method_name]}(request = nil, options: nil, **kwargs)",
+        "      @client.send(:perform_request_raw, #{entry[:operation_id].inspect}, request, options: options, **kwargs)",
+        "    end",
+        ""
+      ]
+    )
+  end
+
+  lines.concat(["  end", ""])
+  lines
+end
+
+def render_surface(class_name, raw_class_name, entries, auth_type:, auth_value_name:)
+  auth_line = auth_type == "none" ? '        auth_value: nil,' : "        auth_value: #{auth_value_name},"
+
+  lines = [
+    "  class #{class_name} < BaseClient",
+    "    attr_reader :raw",
+    "",
+    "    def initialize(base_url:, #{auth_value_name}: nil, headers: nil, timeout: nil, user_agent: nil, retry_options: nil, transport: nil)"
+  ]
+
+  if auth_type == "none"
+    lines[-1] = "    def initialize(base_url:, headers: nil, timeout: nil, user_agent: nil, retry_options: nil, transport: nil)"
+  end
+
+  lines.concat(
+    [
+      "      super(",
+      "        base_url: base_url,",
+      "        auth_type: #{auth_type.inspect},",
+      auth_line,
+      "        headers: headers,",
+      "        timeout: timeout,",
+      "        user_agent: user_agent,",
+      "        retry_options: retry_options,",
+      "        transport: transport",
+      "      )",
+      "      @raw = #{raw_class_name}.new(self)",
+      "    end",
+      ""
+    ]
+  )
+
+  entries.each do |entry|
+    lines.concat(
+      [
+        "    # #{entry[:summary]}",
+        "    def #{entry[:method_name]}(request = nil, options: nil, **kwargs)",
+        "      perform_request(#{entry[:operation_id].inspect}, request, options: options, **kwargs)",
+        "    end",
+        ""
+      ]
+    )
+  end
+
+  lines.concat(["  end", ""])
+  lines
+end
+
+def render_clients(surfaces)
+  lines = [
+    "# Generated by scripts/generate_from_openapi.rb. Do not edit manually.",
+    "",
+    "module LicenseKit",
+    ""
+  ]
+
+  lines.concat(render_surface_raw("ManagementRawClient", surfaces.fetch("management")))
+  lines.concat(render_surface("ManagementClient", "ManagementRawClient", surfaces.fetch("management"), auth_type: "bearer", auth_value_name: "token"))
+  lines.concat(render_surface_raw("RuntimeRawClient", surfaces.fetch("runtime")))
+  lines.concat(render_surface("RuntimeClient", "RuntimeRawClient", surfaces.fetch("runtime"), auth_type: "license", auth_value_name: "license_key"))
+  lines.concat(render_surface_raw("SystemRawClient", surfaces.fetch("system")))
+  lines.concat(render_surface("SystemClient", "SystemRawClient", surfaces.fetch("system"), auth_type: "none", auth_value_name: "unused"))
+  lines.concat(["end", ""])
+  lines.join("\n")
+end
+
+document = YAML.safe_load(File.read(SPEC_PATH), aliases: true)
+paths = document.fetch("paths", {})
+
+metadata_entries = []
+scope_entries = []
+surface_entries = {
+  "management" => [],
+  "runtime" => [],
+  "system" => []
+}
+
+paths.each do |pathname, path_item|
+  next unless path_item.is_a?(Hash)
+
+  path_item.each do |method, operation|
+    next unless operation.is_a?(Hash)
+
+    operation_id = operation["operationId"]
+    next if operation_id.nil? || operation_id.empty?
+
+    auth = infer_auth(operation["security"])
+    summary = operation["summary"] || operation_id
+    success_entries = extract_success_responses(operation["responses"])
+    surface = auth == "bearer" ? "management" : auth == "license" ? "runtime" : "system"
+    method_name = camel_to_snake(operation_id)
+
+    metadata_entries << {
+      operation_id: operation_id,
+      method: method.to_s.upcase,
+      path: pathname,
+      auth: auth,
+      summary: summary,
+      success: success_entries,
+      method_name: method_name
+    }
+
+    surface_entries.fetch(surface) << {
+      operation_id: operation_id,
+      method_name: method_name,
+      summary: summary
+    }
+
+    required_scopes = operation["x-required-scopes"]
+    next unless required_scopes.is_a?(Array)
+
+    scope_entries << {
+      operation_id: operation_id,
+      method: method.to_s.upcase,
+      path: pathname,
+      scopes: required_scopes.map(&:to_s).sort
+    }
+  end
+end
+
+metadata_entries.sort_by! { |entry| entry[:operation_id] }
+scope_entries.sort_by! { |entry| entry[:operation_id] }
+surface_entries.each_value { |entries| entries.sort_by! { |entry| entry[:operation_id] } }
+
+FileUtils.mkdir_p(GENERATED_DIR)
+File.write(File.join(GENERATED_DIR, "metadata.rb"), render_metadata(metadata_entries, surface_entries))
+File.write(File.join(GENERATED_DIR, "operation_scopes.rb"), render_scopes(scope_entries))
+File.write(File.join(GENERATED_DIR, "clients.rb"), render_clients(surface_entries))

data/test/test_client.rb

@@ -0,0 +1,156 @@
+require_relative "test_helper"
+
+class ClientTest < Minitest::Test
+  def test_management_client_normalizes_base_url_and_injects_bearer_auth
+    transport = lambda do |request|
+      assert_equal "https://api.licensekit.dev/api/v1/products?limit=25", request.url
+      assert_equal "Bearer mgmt_test_token", request.headers["Authorization"]
+      assert_equal "application/json", request.headers["Accept"]
+
+      LicenseKit::TransportResponse.new(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: JSON.generate(
+          "data" => [],
+          "meta" => {
+            "request_id" => "req_123",
+            "timestamp" => "2026-03-24T00:00:00Z"
+          }
+        )
+      )
+    end
+
+    client = LicenseKit::ManagementClient.new(
+      base_url: "https://api.licensekit.dev///",
+      token: "mgmt_test_token",
+      transport: transport
+    )
+
+    response = client.list_products(query: { limit: 25 })
+
+    assert_equal [], response["data"]
+  end
+
+  def test_runtime_client_injects_license_auth_and_idempotency_key
+    transport = lambda do |request|
+      assert_equal "License lic_test_key", request.headers["Authorization"]
+      assert_equal "idem_123", request.headers["Idempotency-Key"]
+      assert_equal "application/json", request.headers["Content-Type"]
+      assert_equal "POST", request.method
+      assert_equal({ "fingerprint" => "host-123" }, JSON.parse(request.body))
+
+      LicenseKit::TransportResponse.new(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: JSON.generate(
+          "data" => {
+            "license_id" => "lic_1",
+            "status" => "active",
+            "license_type" => "subscription",
+            "entitlement_version" => 1,
+            "issued_at" => "2026-03-24T00:00:00Z",
+            "next_check_at" => "2026-03-25T00:00:00Z",
+            "device_id" => "dev_1",
+            "features" => []
+          },
+          "signature" => {
+            "alg" => "Ed25519",
+            "kid" => "kid_1",
+            "value" => "AQID"
+          },
+          "meta" => {
+            "request_id" => "req_runtime",
+            "timestamp" => "2026-03-24T00:00:00Z"
+          }
+        )
+      )
+    end
+
+    client = LicenseKit::RuntimeClient.new(
+      base_url: "https://api.licensekit.dev",
+      license_key: "lic_test_key",
+      transport: transport
+    )
+
+    response = client.activate_license(
+      body: { "fingerprint" => "host-123" },
+      idempotency_key: "idem_123"
+    )
+
+    assert_equal "lic_1", response["data"]["license_id"]
+  end
+
+  def test_system_client_health_alias_and_readyz_503_are_successes
+    transport = lambda do |request|
+      body =
+        if request.url.end_with?("/health")
+          {
+            "data" => { "status" => "ok" },
+            "meta" => {
+              "request_id" => "req_health",
+              "timestamp" => "2026-03-24T00:00:00Z"
+            }
+          }
+        elsif request.url.end_with?("/readyz")
+          {
+            "data" => { "status" => "not_ready", "db" => "down" },
+            "meta" => {
+              "request_id" => "req_ready",
+              "timestamp" => "2026-03-24T00:00:00Z"
+            }
+          }
+        else
+          raise "Unexpected path: #{request.url}"
+        end
+
+      status = request.url.end_with?("/readyz") ? 503 : 200
+      LicenseKit::TransportResponse.new(
+        status: status,
+        headers: { "Content-Type" => "application/json" },
+        body: JSON.generate(body)
+      )
+    end
+
+    client = LicenseKit::SystemClient.new(
+      base_url: "https://api.licensekit.dev",
+      transport: transport
+    )
+
+    health = client.health
+    ready = client.raw.readyz
+
+    assert_equal "ok", health["data"]["status"]
+    assert_equal 503, ready.status
+    assert_equal "not_ready", ready.data["data"]["status"]
+  end
+
+  def test_error_envelopes_raise_api_error
+    transport = lambda do |_request|
+      LicenseKit::TransportResponse.new(
+        status: 403,
+        headers: { "Content-Type" => "application/json" },
+        body: JSON.generate(
+          "error" => {
+            "code" => "TOKEN_SCOPE_DENIED",
+            "message" => "scope denied"
+          },
+          "meta" => {
+            "request_id" => "req_forbidden",
+            "timestamp" => "2026-03-24T00:00:00Z"
+          }
+        )
+      )
+    end
+
+    client = LicenseKit::ManagementClient.new(
+      base_url: "https://api.licensekit.dev",
+      token: "mgmt_test_token",
+      transport: transport
+    )
+
+    error = assert_raises(LicenseKit::ApiError) { client.list_products }
+    assert_equal 403, error.status
+    assert_equal "TOKEN_SCOPE_DENIED", error.code
+    assert_equal "req_forbidden", error.request_id
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "base64"
+require "json"
+require "minitest/autorun"
+require "licensekit"

data/test/test_scopes.rb

@@ -0,0 +1,14 @@
+require_relative "test_helper"
+
+class ScopesTest < Minitest::Test
+  def test_get_required_scopes
+    scopes = LicenseKit.get_required_scopes("createProduct")
+    assert_equal ["product:write"], scopes
+  end
+
+  def test_has_required_scopes
+    assert_equal true, LicenseKit.has_required_scopes("createProduct", ["product:write"])
+    assert_equal true, LicenseKit.has_required_scopes("createProduct", ["admin"])
+    assert_equal false, LicenseKit.has_required_scopes("createProduct", ["product:read"])
+  end
+end

data/test/test_verification.rb

@@ -0,0 +1,44 @@
+require_relative "test_helper"
+require "ed25519"
+
+class VerificationTest < Minitest::Test
+  def test_verify_runtime_payload_and_tamper_detection
+    signing_key = Ed25519::SigningKey.generate
+    verify_key = signing_key.verify_key
+    payload = {
+      "license_id" => "lic_1",
+      "status" => "active"
+    }
+    payload_bytes = '{"license_id":"lic_1","status":"active"}'
+    signature_bytes = signing_key.sign(payload_bytes)
+    key_store = LicenseKit::PublicKeyStore.new(
+      [
+        {
+          "kid" => "kid_live",
+          "algorithm" => "Ed25519",
+          "public_key" => Base64.strict_encode64(verify_key.to_bytes),
+          "status" => "active",
+          "created_at" => "2026-03-24T00:00:00Z"
+        }
+      ]
+    )
+    signature = {
+      "alg" => "Ed25519",
+      "kid" => "kid_live",
+      "value" => Base64.strict_encode64(signature_bytes)
+    }
+
+    verified = LicenseKit.verify_runtime_payload(payload, signature, key_store)
+    tampered = LicenseKit.verify_runtime_result(
+      {
+        "data" => payload.merge("status" => "revoked"),
+        "signature" => signature
+      },
+      key_store
+    )
+
+    assert_equal true, verified.ok
+    assert_equal "kid_live", verified.key["kid"]
+    assert_equal false, tampered.ok
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: licensekit-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.0
+platform: ruby
+authors:
+- David Main
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+description: Typed-ish Ruby SDK for the LicenseKit licensing API with management,
+  runtime, and system clients plus Ed25519 verification helpers.
+email:
+- dtmain@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- README.md
+- examples/01_create_scoped_api_key.rb
+- examples/02_runtime_validate_and_verify.rb
+- lib/licensekit.rb
+- lib/licensekit/client.rb
+- lib/licensekit/errors.rb
+- lib/licensekit/generated/clients.rb
+- lib/licensekit/generated/metadata.rb
+- lib/licensekit/generated/operation_scopes.rb
+- lib/licensekit/scopes.rb
+- lib/licensekit/types.rb
+- lib/licensekit/verification.rb
+- lib/licensekit/version.rb
+- openapi/openapi.yaml
+- scripts/generate_from_openapi.rb
+- test/test_client.rb
+- test/test_helper.rb
+- test/test_scopes.rb
+- test/test_verification.rb
+homepage: https://licensekit.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://licensekit.dev
+  documentation_uri: https://licensekit.dev/docs/agent-quickstart
+  changelog_uri: https://github.com/drmain1/licensekit-ruby/releases
+  bug_tracker_uri: https://github.com/drmain1/licensekit-ruby/issues
+  source_code_uri: https://github.com/drmain1/licensekit-ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the LicenseKit licensing API
+test_files: []