licentivo-sdk 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 998ed5c517528b8aa65ef3c83722dbcf39ad178e5c0a0008983ccd9837bfaf3a
+  data.tar.gz: ca64986426a30cfa1c96baeba82af59b8ad1b24b6051d22f5e192d8f886b0930
+SHA512:
+  metadata.gz: 13f47cb98e670d8c315359af3290721410b733258fbbe0fce5d65b253eac574500276373be935649ff5b14826f51d1860cebb9663da500bf2ab302a10dcd5c61
+  data.tar.gz: 694ec4cf2631aef6abe1596ded72a0201b480f64235a13f12f750bca4c211397a7c0dabd62ed85e4a4c831fe95f40acf16d627ef7956c0a78f0a683b008b9b43

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spf86 and Licentivo contributors
+
+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/NOTICE

@@ -0,0 +1,17 @@
+Licentivo client SDKs
+Copyright (c) 2026 spf86 and Licentivo contributors
+Project: https://github.com/spf86/licentivo-sdk
+
+The MIT license applies to the Licentivo client SDK code, examples and
+installation tools. The licensing server and administration application are
+separate software and are not included in this SDK distribution.
+
+Bundled third-party source retains its original license:
+- cJSON: see sdk/c/vendor/cJSON-LICENSE (or c/vendor/cJSON-LICENSE).
+- Monocypher and its Ed25519 extension: see
+  sdk/c/vendor/Monocypher-LICENCE.md (or c/vendor/Monocypher-LICENCE.md).
+Native packages include these files in the licenses directory.
+
+External dependencies such as libcurl, OpenSSL, cryptography, undici and
+BouncyCastle retain their own licenses. Their installation is handled by
+the corresponding package manager or the target system.

data/README.md

@@ -0,0 +1,80 @@
+# Licentivo Ruby SDK
+
+Add software licensing to a Ruby application with a block-based interface and a bundled native licensing core.
+
+## Features
+
+- Activates or restores a license with a private machine-scoped device credential.
+- Verifies pinned signatures, checks expiry and feature access, and protects your business block.
+- Runs policy heartbeats, supports permitted offline use and floating-seat cleanup.
+- Handles metered-feature reserve/commit/cancel and journals pending settlement across restarts.
+- Supports refresh, explicit device deactivation, offline file activation and structured error diagnostics.
+
+Your application provides the activation interface, the actual business block and durable business results. The SDK manages licensing; customer credentials and vendor management keys do not belong in distributed packages.
+
+## Installation and runtime requirements
+
+Start with the repository's `QUICKSTART.md`. The application in
+`examples/quickstart.rb` activates/restores a device and actually exports a file.
+It also supports `LICENTIVO_METERED=1` with a stable `LICENTIVO_OPERATION_ID`.
+
+Prerequisites: Ruby 3.1+ with Fiddle, a C11 compiler and libcurl development files.
+Linux also needs OpenSSL development files. Installing a source gem requires make
+(RubyInstaller Devkit/MSYS2 on Windows). A matching precompiled platform gem
+includes the core and installs without a C compiler; Windows also includes the
+matching libcurl DLL and its license. The platform gem still requires Fiddle.
+The source launcher builds the bundled
+core automatically. For a source gem, RubyGems builds it during installation.
+Windows uses MinGW and a matching libcurl package; set `LICENTIVO_CURL_ROOT` and add
+its `bin` directory to the process's PATH. Physical macOS acceptance is pending.
+
+Install the pinned RubyGems release, or add it to your application's Gemfile:
+
+```bash
+gem install licentivo-sdk --version 0.10.0
+```
+
+```ruby
+gem 'licentivo-sdk', '= 0.10.0'
+```
+
+The [common website installer](https://www.licentivo.com/en/docs.html#sdk) with `ruby` also selects and installs a verified matching platform gem. It prints the per-terminal GEM_PATH command; platform gems avoid a local C build. A complete local source bundle can also be used:
+
+```ruby
+# Gemfile
+gem 'licentivo-sdk', path: 'SDK_ROOT/sdk/ruby'
+```
+
+For a path gem, run `ruby SDK_ROOT/sdk/ruby/build_native.rb` before starting your
+application. A built `.gem` runs this compilation automatically during `gem install`.
+The SDK does not download executable code when you require it.
+
+```ruby
+require 'licentivo'
+
+Licentivo::Client.open_with_license('product.json', customer_key) do |client|
+  client.run_feature('export') { File.write('report.txt', "Your result\n") }
+  # A real application keeps client alive through its main loop.
+end
+```
+
+`run_metered_feature('export', 1, job_id) { your_operation }` handles reserve,
+business execution, commit and cancellation. It returns an `Execution` with
+`executed` and `value`; `replay?` means the business block was skipped and you
+should load its existing result using the job ID. Exceptions are re-raised after
+the core handles cancellation. If the process dies during the block, check the
+real business outcome and call `resolve_metered_feature(job_id, true_or_false)`.
+
+Use one distinct stable ID per job; separate processes must not execute the same
+ID. Do not close or start another workflow from inside a business block. Status
+reads are available there. The client serializes native access; policy heartbeats
+run inside the core without entering Ruby. Poll `status` or `feature_status` for
+your UI and marshal updates to its thread.
+
+`Licentivo::Error` exposes `code`, `http_status`, `request_id`, `retryable` and
+`retry_after_seconds`. Online refresh, explicit deactivate, offline exchange and
+low-level metering methods are also provided. Use `close` or the owning block's
+ensure cleanup on shutdown; normal exits retain node-locked device registration.
+
+Do not ship test keys, `sdk-demo.json`, credentials, caches or management API keys.
+TLS and pinned signatures stay enabled. Licenses accompany the vendored core.

data/build_native.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# Compiles the shared licensing core without downloading anything or modifying
+# system settings. Source bundles ship canonical copies under native/.
+require 'fileutils'
+require 'open3'
+require 'rbconfig'
+require 'shellwords'
+
+package = File.expand_path(__dir__)
+bundled = File.join(package, 'native')
+core = File.file?(File.join(bundled, 'licentivo.c')) ? bundled : File.expand_path('../c', package)
+windows = RbConfig::CONFIG['host_os'].match?(/mswin|mingw/)
+mac = RbConfig::CONFIG['host_os'].include?('darwin')
+extension = windows ? 'dll' : mac ? 'dylib' : 'so'
+output = ARGV[0] || File.join(package, 'lib/licentivo/native', "licentivo_native.#{extension}")
+FileUtils.mkdir_p(File.dirname(output))
+compiler = Shellwords.split(ENV.fetch('CC', windows ? 'gcc' : 'cc'))
+command = compiler + ['-std=c11', '-O2', "-I#{core}"]
+command << '-fPIC' unless windows
+command << (mac ? '-dynamiclib' : '-shared')
+command << '-Wl,--export-all-symbols' if windows
+curl = ENV['LICENTIVO_CURL_ROOT']
+if curl && !curl.empty?
+  command << "-I#{File.join(curl, 'include')}"
+  command << "-L#{File.join(curl, 'lib')}"
+elsif windows
+  abort 'Set LICENTIVO_CURL_ROOT to your matching libcurl development folder. See README.md.'
+elsif system('pkg-config', '--exists', 'libcurl', 'openssl', out: File::NULL, err: File::NULL)
+  flags, status = Open3.capture2('pkg-config', '--cflags', '--libs', 'libcurl', 'openssl')
+  abort 'pkg-config failed' unless status.success?
+  # Library options belong after the object/source files in the linker command.
+  includes, libraries = Shellwords.split(flags).partition { |flag| flag.start_with?('-I', '-D') }
+  command.concat(includes)
+end
+command.concat(%w[licentivo.c vendor/cJSON.c vendor/monocypher.c vendor/monocypher-ed25519.c].map { |file| File.join(core, file) })
+command.concat(libraries || ['-lcurl'])
+command.concat(windows ? %w[-lbcrypt -ladvapi32] : %w[-lcrypto -lpthread -lm])
+command.concat(['-o', output])
+abort 'Native core build failed. Install a C11 compiler and libcurl/OpenSSL development files.' unless system(*command)
+if windows && curl
+  dlls = Dir[File.join(File.expand_path(curl), 'bin', 'libcurl*.dll')]
+  abort 'The matching runtime libcurl DLL is missing' if dlls.empty?
+  dlls.each { |dll| FileUtils.cp(dll, File.dirname(output)) }
+  license = [File.join(curl, 'COPYING'), File.join(curl, 'COPYING.txt')].find { |file| File.file?(file) }
+  abort 'The libcurl license is missing' unless license
+  FileUtils.cp(license, File.join(File.dirname(output), 'libcurl-LICENSE'))
+end
+puts "Native licensing core built: #{output}"

data/examples/app.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require_relative '../lib/licentivo'
+
+def ask(label)
+  print label
+  $stdout.flush
+  $stdin.gets&.strip || ''
+end
+
+def export_report
+  File.write('licensed-report.txt', "A report generated by the licensed application.\n")
+  puts 'Saved licensed-report.txt'
+end
+
+config = ARGV[0] || 'product.json'
+key = ENV.fetch('LICENTIVO_LICENSE_KEY', '')
+client = nil
+begin
+  begin
+    client = Licentivo::Client.open_with_license(config, key)
+  rescue Licentivo::Error => error
+    warn error.message
+    key = ask('Customer activation key (not a management API key): ')
+    client = Licentivo::Client.open_with_license(config, key)
+  end
+  loop do
+    puts "\n1 Status | 2 Export | 3 Metered export | 4 Refresh | 5 Transfer device | 0 Quit"
+    choice = ask('> ')
+    break if choice == '0' || choice.empty?
+    begin
+      case choice
+      when '1' then puts JSON.pretty_generate(client.status)
+      when '2' then client.run_feature('export') { export_report }
+      when '3'
+        id = ask('Stable job ID (reuse only to recover this same job): ')
+        result = client.run_metered_feature('export', 1, id) { export_report }
+        puts 'Existing job confirmed; export was not repeated' if result.replay?
+      when '4' then client.refresh_online
+      when '5'
+        if ask('Type TRANSFER to explicitly unbind this device: ') == 'TRANSFER'
+          client.deactivate
+          puts 'Device unbound; reactivate on the destination device'
+          break
+        end
+      else puts 'Choose a menu number'
+      end
+    rescue StandardError => error
+      warn error.message
+    end
+  end
+rescue StandardError => error
+  warn error.message
+  exit 2
+ensure
+  client&.close # Always stop heartbeat; normal exit retains device registration.
+end

data/examples/quickstart.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+require_relative '../lib/licentivo'
+
+def setting(name, fallback)
+  value = ENV[name]
+  value.nil? || value.empty? ? fallback : value
+end
+
+def export_report(path)
+  # Replace this write with your existing export operation.
+  File.write(path, "A report generated by the licensed application.\n")
+end
+
+begin
+  # A GUI supplies the activation input. Later starts use an empty key.
+  Licentivo::Client.open_with_license(
+    setting('LICENTIVO_CONFIG', 'product.json'),
+    setting('LICENTIVO_LICENSE_KEY', '')
+  ) do |client|
+    feature = setting('LICENTIVO_FEATURE', 'export')
+    path = setting('LICENTIVO_OUTPUT', 'licensed-report.txt')
+    if setting('LICENTIVO_METERED', '0') == '1'
+      client.run_metered_feature(feature, 1, setting('LICENTIVO_OPERATION_ID', '')) { export_report(path) }
+    else
+      client.run_feature(feature) { export_report(path) }
+    end
+    puts "License OK: #{feature} is available\nExport completed: #{path}"
+  end # Real app: keep the owning block/client alive until shutdown.
+rescue StandardError => error
+  warn error.message
+  exit 2
+end

data/examples/vectors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+require_relative '../lib/licentivo'
+
+fixture = JSON.parse(File.read(ARGV[0] || 'tests/lease-vectors.json'))
+fixture.fetch('vectors').each do |vector|
+  actual = Licentivo.verify_lease(vector['envelope'], fixture['trusted_keys'],
+    vector['product_id'], vector['device_id'], vector['now'])
+  abort "Ruby vector failed: #{vector['name']}" unless actual == vector['valid']
+end
+puts "Ruby security core: #{fixture['vectors'].length} lease vectors passed"

data/ext/licentivo_native/extconf.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require 'mkmf'
+
+package = File.expand_path('../..', __dir__)
+core = File.join(package, 'native')
+abort 'Bundled native core is missing' unless File.file?(File.join(core, 'licentivo.c'))
+$INCFLAGS << " -I#{Shellwords.escape(core)}"
+$VPATH.concat([core, File.join(core, 'vendor')])
+$srcs = %w[licentivo.c cJSON.c monocypher.c monocypher-ed25519.c]
+$CFLAGS << ' -std=c11'
+curl = ENV['LICENTIVO_CURL_ROOT']
+if curl && !curl.empty?
+  dir_config('curl', File.join(curl, 'include'), File.join(curl, 'lib'))
+end
+abort 'libcurl development files are required' unless have_header('curl/curl.h') && have_library('curl', 'curl_easy_init')
+if RbConfig::CONFIG['host_os'].match?(/mswin|mingw/)
+  $DLDFLAGS << ' -Wl,--export-all-symbols'
+  have_library('bcrypt')
+  have_library('advapi32')
+else
+  abort 'OpenSSL development files are required' unless have_header('openssl/evp.h') && have_library('crypto', 'EVP_sha256')
+  have_library('pthread')
+  have_library('m')
+end
+# Fiddle loads this library directly. It contains no Ruby C API calls or Init_*
+# hook; the target path is also used by the standalone source build script.
+create_makefile('licentivo/native/licentivo_native')

data/lib/licentivo.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+require 'fiddle'
+require 'json'
+require 'monitor'
+
+module Licentivo
+  VERSION = '0.10.0'
+
+  class Error < StandardError
+    attr_reader :code, :http_status, :request_id, :retryable, :retry_after_seconds
+    def initialize(message, code: 'SDK_ERROR', http_status: 0, request_id: '', retryable: false, retry_after_seconds: 0)
+      @code, @http_status, @request_id = code, http_status, request_id
+      @retryable, @retry_after_seconds = retryable, retry_after_seconds
+      super("#{code}: #{message}#{request_id.empty? ? '' : " (request #{request_id})"}")
+    end
+  end
+
+  Execution = Struct.new(:value, :executed, keyword_init: true) do
+    def replay? = !executed
+  end
+
+  # This library does not register Ruby callbacks on the native heartbeat thread.
+  # Local status reads can be marshalled by the application to its own UI thread.
+  module Native
+    module_function
+    def library
+      @library ||= begin
+        suffix = case RUBY_PLATFORM
+                 when /mswin|mingw/ then 'dll'
+                 when /darwin/ then 'dylib'
+                 else 'so'
+                 end
+        folder = File.expand_path('licentivo/native', __dir__)
+        path = ENV['LICENTIVO_NATIVE_LIBRARY'] || [suffix, 'so', 'dll', 'dylib'].uniq.map { |ext| File.join(folder, "licentivo_native.#{ext}") }.find { |file| File.file?(file) }
+        path ||= File.join(folder, "licentivo_native.#{suffix}")
+        unless File.file?(path)
+          raise LoadError, 'Licentivo native core is missing. Run ruby sdk/ruby/build_native.rb for a source bundle, or install the compiled gem. See sdk/ruby/README.md.'
+        end
+        if suffix == 'dll'
+          # Ruby's Windows loader does not search process PATH for dependent
+          # DLLs. Load the matching libcurl explicitly and keep its handle alive.
+          candidates = Dir[File.join(File.dirname(path), 'libcurl*.dll')]
+          if ENV['LICENTIVO_CURL_ROOT']
+            candidates.concat(Dir[File.join(File.expand_path(ENV['LICENTIVO_CURL_ROOT']), 'bin', 'libcurl*.dll')])
+          end
+          @curl_library = Fiddle.dlopen(candidates.first) unless candidates.empty?
+        end
+        Fiddle.dlopen(path)
+      end
+    end
+    def bind(name, arguments, result)
+      # Release the GVL while the core uses the network. Fiddle closures acquire
+      # it again before entering a Ruby block; native heartbeats never enter Ruby.
+      Fiddle::Function.new(library[name], arguments, result, need_gvl: false)
+    end
+    def functions
+      @functions ||= begin
+        p, i, q = Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_LONG_LONG
+        signatures = {
+          init: ['ln_init_file_with_license', [p,p], p],
+          start: ['ln_start', [p], i], destroy: ['ln_destroy', [p], Fiddle::TYPE_VOID],
+          last_error: ['ln_last_error', [p], p], error_info: ['ln_get_error_info', [p,p], i],
+          status: ['ln_status', [p], p], feature_status: ['ln_feature_status', [p,p], p],
+          run_feature: ['ln_run_feature', [p,p,p,p], i],
+          run_metered_feature: ['ln_run_metered_feature', [p,p,q,p,p,p], i],
+          resolve_metered_feature: ['ln_resolve_metered_feature', [p,p,i], i],
+          validate: ['ln_validate', [p], i], heartbeat: ['ln_heartbeat', [p], i],
+          refresh_online: ['ln_refresh_online', [p], i], deactivate: ['ln_deactivate', [p], i],
+          reserve: ['ln_reserve', [p,p,q,p], p], consume: ['ln_consume', [p,p,q,p], p],
+          commit: ['ln_commit', [p,p,p], p], cancel: ['ln_cancel', [p,p,p], p],
+          offline_request: ['ln_offline_request', [p,p], p], import_offline: ['ln_import_offline', [p,p,p], i],
+          free_string: ['ln_free_string', [p], Fiddle::TYPE_VOID],
+          json: ['ln_json', [p], p], delete_json: ['cJSON_Delete', [p], Fiddle::TYPE_VOID],
+          verify: ['ln_verify', [p,p,p,p,q], i]
+        }
+        signatures.transform_values { |name, args, result| bind(name, args, result) }
+      end
+    end
+    def call(name, *arguments) = functions.fetch(name).call(*arguments)
+    def input(value)
+      value = String(value)
+      raise ArgumentError, 'Input must not contain NUL bytes' if value.include?("\0")
+      value + "\0"
+    end
+    def text(pointer) = pointer.null? ? '' : pointer.to_s.force_encoding(Encoding::UTF_8)
+    def owned_json(pointer)
+      raise Error.new('Native core returned no result', code: 'INVALID_RESPONSE') if pointer.null?
+      begin
+        JSON.parse(pointer.to_s)
+      ensure
+        call(:free_string, pointer)
+      end
+    end
+  end
+
+  class Client
+    def self.open_with_license(path, customer_key = '')
+      client = new(path, customer_key)
+      begin
+        client.start
+      rescue Exception
+        client.close
+        raise
+      end
+      return client unless block_given?
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    def initialize(path, customer_key = '')
+      @lock, @in_callback = Monitor.new, false
+      @native = Native.call(:init, Native.input(path), Native.input(customer_key))
+      if @native.null?
+        @native = nil
+        raise Error.new('Check product.json, pinned keys and local storage', code: 'CONFIGURATION_ERROR')
+      end
+    end
+
+    def start = checked(:start)
+    def validate = checked(:validate)
+    def heartbeat = checked(:heartbeat)
+    def refresh_online = checked(:refresh_online)
+    def deactivate = checked(:deactivate)
+    def status = read_json(:status)
+    def feature_status(feature) = read_json(:feature_status, Native.input(feature))
+    def reserve(feature, quantity, job_id) = read_json(:reserve, Native.input(feature), integer(quantity), Native.input(job_id))
+    def consume(feature, quantity, job_id) = read_json(:consume, Native.input(feature), integer(quantity), Native.input(job_id))
+    def commit(reservation_id, job_id) = read_json(:commit, Native.input(reservation_id), Native.input(job_id))
+    def cancel(reservation_id, job_id) = read_json(:cancel, Native.input(reservation_id), Native.input(job_id))
+    def offline_request(operation = 'activate') = read_json(:offline_request, Native.input(operation))
+    def import_offline(request, response) = checked(:import_offline, Native.input(JSON.generate(request)), Native.input(JSON.generate(response)))
+    def resolve_metered_feature(job_id, business_succeeded)
+      unless business_succeeded == true || business_succeeded == false
+        raise ArgumentError, 'Determine the real business outcome; pass true or false'
+      end
+      checked(:resolve_metered_feature, Native.input(job_id), business_succeeded ? 1 : 0)
+    end
+
+    def run_feature(feature, &action)
+      execution = run_callback(:run_feature, Native.input(feature), &action)
+      execution.value
+    end
+    def run_metered_feature(feature, quantity, job_id, &action)
+      run_callback(:run_metered_feature, Native.input(feature), integer(quantity), Native.input(job_id), &action)
+    end
+
+    def close
+      @lock.synchronize do
+        raise Error.new('Do not close this client inside its business callback', code: 'WORKFLOW_BUSY') if @in_callback
+        if @native
+          Native.call(:destroy, @native)
+          @native = nil
+        end
+      end
+      nil
+    end
+
+    private
+    def integer(value)
+      raise ArgumentError, 'Quantity must be a positive signed 64-bit integer' unless value.is_a?(Integer) && value.positive? && value <= 0x7fff_ffff_ffff_ffff
+      value
+    end
+    def active
+      raise Error.new('Client is closed', code: 'CLIENT_CLOSED') unless @native
+      @native
+    end
+    def error
+      # ln_error_info: int, char[80], char[128], int, int; the shared ABI uses
+      # 32-bit ints on supported Windows/Linux/macOS targets.
+      info = Fiddle::Pointer.malloc(220, Fiddle::RUBY_FREE)
+      info[0,220] = "\0" * 220
+      Native.call(:error_info, @native, info)
+      Error.new('The licensing operation did not complete',
+        code: info[4,80].split("\0", 2).first,
+        http_status: info[0,4].unpack1('i'), request_id: info[84,128].split("\0", 2).first,
+        retryable: info[212,4].unpack1('i') != 0, retry_after_seconds: info[216,4].unpack1('i'))
+    end
+    def checked(name, *arguments)
+      @lock.synchronize { raise error if Native.call(name, active, *arguments) == 0 }
+      true
+    end
+    def read_json(name, *arguments)
+      @lock.synchronize do
+        pointer = Native.call(name, active, *arguments)
+        raise error if pointer.null?
+        Native.owned_json(pointer)
+      end
+    end
+    def run_callback(name, *arguments)
+      raise ArgumentError, 'Supply your business operation as a block' unless block_given?
+      @lock.synchronize do
+        raise Error.new('A business callback is already running', code: 'WORKFLOW_BUSY') if @in_callback
+        execution = Execution.new(executed: false)
+        business_error = nil
+        callback = Fiddle::Closure::BlockCaller.new(Fiddle::TYPE_INT, [Fiddle::TYPE_VOIDP]) do |_context|
+          @in_callback = true
+          begin
+            execution.executed = true
+            execution.value = yield
+            1
+          rescue Exception => exception
+            # Exceptions never cross the C boundary. The native workflow settles
+            # cancellation (or journals a pending cancellation) before re-raising.
+            business_error = exception
+            0
+          ensure
+            @in_callback = false
+          end
+        end
+        ok = Native.call(name, active, *arguments, callback, 0)
+        raise business_error if business_error
+        raise error if ok == 0
+        execution
+      end
+    end
+  end
+
+  def self.verify_lease(envelope, pins, product, device, now)
+    parsed_envelope = Native.call(:json, Native.input(JSON.generate(envelope)))
+    parsed_pins = Native.call(:json, Native.input(JSON.generate(pins)))
+    begin
+      Native.call(:verify, parsed_envelope, parsed_pins, Native.input(product), Native.input(device), Integer(now)) != 0
+    ensure
+      Native.call(:delete_json, parsed_envelope)
+      Native.call(:delete_json, parsed_pins)
+    end
+  end
+end

data/native/feature_tasks.h

@@ -0,0 +1,72 @@
+/* Included by licentivo.c only. Private task IDs/outcome, never business data. */
+static int task_error(ln_client*c,const char*code){lock(c);snprintf(c->error,sizeof(c->error),"%s",code);c->http_status=0;c->retryable=0;c->request_id[0]=0;view_lock(c);int online=c->view_online;view_unlock(c);publish(c,online);unlock(c);return 0;}
+static int task_enter(ln_client*c){view_lock(c);int busy=c->task_busy;if(!busy)c->task_busy=1;view_unlock(c);return !busy;}
+static void task_leave(ln_client*c){view_lock(c);c->task_busy=0;view_unlock(c);}
+static char*task_path(ln_client*c,const char*id){
+ if(!id||!id[0]||strlen(id)>80)return NULL;
+ for(const unsigned char*p=(const unsigned char*)id;*p;p++)if(*p<33||*p>126)return NULL;
+ char source[65],digest[65],input[256];lock(c);
+ const char*key=text(c->cfg,"license_key");int ok=key&&key[0]?hash(key,source):text(c->auth,"source_hash")!=NULL;
+ if(ok&&(!key||!key[0]))snprintf(source,sizeof(source),"%s",text(c->auth,"source_hash"));unlock(c);
+ if(!ok)return NULL;snprintf(input,sizeof(input),"%s\n%s",source,id);if(!hash(input,digest))return NULL;
+ const char*cache=text(c->cfg,"cache_path");if(!cache)return NULL;
+ char*path=malloc(strlen(cache)+78);if(path)sprintf(path,"%s.task-%s.json",cache,digest);return path;
+}
+static cJSON*task_read(const char*path,const char*id){
+ struct stat info;if(stat(path,&info)==0){if(info.st_size>4096)return NULL;char*raw=readfile(path,4096);cJSON*task=raw?ln_json(raw):NULL;free(raw);int64_t version;
+  int64_t quantity;
+  if(!task||!num(task,"version",&version)||version!=1||!text(task,"operation_id")||strcmp(text(task,"operation_id"),id)||!text(task,"reservation_id")||!text(task,"reservation_id")[0]||!text(task,"state")||!text(task,"feature")||!text(task,"feature")[0]||!num(task,"quantity",&quantity)||quantity<=0){cJSON_Delete(task);return NULL;}return task;
+ }
+ if(errno!=ENOENT)return NULL;
+ cJSON*task=cJSON_CreateObject();cJSON_AddNumberToObject(task,"version",1);cJSON_AddStringToObject(task,"operation_id",id);cJSON_AddStringToObject(task,"reservation_id","");cJSON_AddStringToObject(task,"state","");return task;
+}
+static void task_state(cJSON*task,const char*state){cJSON_ReplaceItemInObjectCaseSensitive(task,"state",cJSON_CreateString(state));}
+static int task_finish(ln_client*c,const char*path,cJSON*task,int succeeded){
+ char*raw=succeeded?ln_commit(c,text(task,"reservation_id"),text(task,"operation_id")):ln_cancel(c,text(task,"reservation_id"),text(task,"operation_id"));
+ cJSON*receipt=raw?ln_json(raw):NULL;ln_free_string(raw);if(!receipt)return 0;
+ const char*state=text(receipt,"status"),*expected=succeeded?"committed":"canceled";
+ int ok=state&&!strcmp(state,expected);cJSON_Delete(receipt);
+ if(!ok)return task_error(c,"RESERVATION_CLOSED");task_state(task,expected);
+ return write_state(path,task)?1:task_error(c,"TASK_JOURNAL_ERROR");
+}
+int ln_run_metered_feature(ln_client*c,const char*feature,int64_t quantity,const char*id,ln_feature_action action,void*context){
+ if(!c||!feature||!action||quantity<=0)return c?task_error(c,"TASK_INPUT_INVALID"):0;
+ if(!task_enter(c))return task_error(c,"TASK_BUSY");
+ int ok=0;char*path=task_path(c,id);cJSON*task=path?task_read(path,id):NULL;
+ if(!task){task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ const char*state=text(task,"state");
+ if(state[0]){int64_t old_quantity;if(!text(task,"feature")||strcmp(text(task,"feature"),feature)||!num(task,"quantity",&old_quantity)||old_quantity!=quantity){task_error(c,"OPERATION_ID_CONFLICT");goto done;}}
+ if(!state[0]){cJSON_AddStringToObject(task,"feature",feature);cJSON_AddNumberToObject(task,"quantity",(double)quantity);}
+ if(!strcmp(state,"committed")){ok=1;goto done;}
+ if(!strcmp(state,"commit_pending")){ok=task_finish(c,path,task,1);goto done;}
+ if(!strcmp(state,"cancel_pending")){if(!task_finish(c,path,task,0))goto done;task_error(c,"OPERATION_CANCELED");goto done;}
+ if(!strcmp(state,"canceled")){task_error(c,"OPERATION_CANCELED");goto done;}
+ if(!strcmp(state,"business_running")){task_error(c,"BUSINESS_OUTCOME_UNKNOWN");goto done;}
+ if(state[0]){task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ if(!ln_check_feature(c,feature)){task_error(c,"FEATURE_NOT_ENTITLED");goto done;}
+ char*raw=ln_reserve(c,feature,quantity,id);cJSON*hold=raw?ln_json(raw):NULL;ln_free_string(raw);
+ if(!hold)goto done;
+ const char*held=text(hold,"status");
+ if(held&&!strcmp(held,"committed")){cJSON_ReplaceItemInObjectCaseSensitive(task,"reservation_id",cJSON_CreateString(text(hold,"reservation_id")));task_state(task,"committed");cJSON_Delete(hold);ok=write_state(path,task)?1:task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ if(!held||strcmp(held,"pending")||!text(hold,"reservation_id")){cJSON_Delete(hold);task_error(c,"RESERVATION_CLOSED");goto done;}
+ cJSON_ReplaceItemInObjectCaseSensitive(task,"reservation_id",cJSON_CreateString(text(hold,"reservation_id")));cJSON_Delete(hold);task_state(task,"business_running");
+ if(!write_state(path,task)){raw=ln_cancel(c,text(task,"reservation_id"),id);ln_free_string(raw);task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ if(!action(context)){
+  task_state(task,"cancel_pending");if(write_state(path,task))task_finish(c,path,task,0);task_error(c,"BUSINESS_ACTION_FAILED");goto done;
+ }
+ task_state(task,"commit_pending");if(!write_state(path,task)){task_error(c,"BUSINESS_COMPLETED_JOURNAL_ERROR");goto done;}
+ ok=task_finish(c,path,task,1);
+done:
+ cJSON_Delete(task);free(path);task_leave(c);return ok;
+}
+int ln_resolve_metered_feature(ln_client*c,const char*id,int succeeded){
+ if(!c)return 0;if(!task_enter(c))return task_error(c,"TASK_BUSY");
+ int ok=0;char*path=task_path(c,id);cJSON*task=path?task_read(path,id):NULL;
+ if(!task){task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ const char*state=text(task,"state");if(!strcmp(state,succeeded?"committed":"canceled")){ok=1;goto done;}
+ if(!text(task,"reservation_id")[0]||(strcmp(state,"business_running")&&strcmp(state,"commit_pending")&&strcmp(state,"cancel_pending"))||(!succeeded&&!strcmp(state,"commit_pending"))||(succeeded&&!strcmp(state,"cancel_pending"))){task_error(c,"TASK_OUTCOME_CONFLICT");goto done;}
+ task_state(task,succeeded?"commit_pending":"cancel_pending");if(!write_state(path,task)){task_error(c,"TASK_JOURNAL_ERROR");goto done;}
+ ok=task_finish(c,path,task,succeeded);
+done:
+ cJSON_Delete(task);free(path);task_leave(c);return ok;
+}