globiguard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfe6ca1d82d5c27cd8b501fbf9306911785035cd09384c41e081e1c286cac576
+  data.tar.gz: ae191efdeca8f3ca701fdfd999878bdb46e60e1ca473e87db8af0d997a678957
+SHA512:
+  metadata.gz: 698b401af1ea2603753d2d99093bfc559a87b5c0b02ca30a5e59c0cb071f3a088d10ab2849a86d976fffcb35fc2049fb96d7896b88d72aaf96fd12492d1d0cd9
+  data.tar.gz: c0dd8138ca55a3575ab55df1e829a0660caf014ef09ff42e15639dc9c98d5f47b3c9072d015b2cdf054d501c40a706852b64db6de751d7bcfa1d0db8a4e07694

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial dependency-minimal Ruby SDK foundation.
+- Added credential helpers, safe request transport, resource clients, governed action helpers, trust webhook verification, bootstrap helpers, and offline entitlement manifest verification through Ruby OpenSSL Ed25519 support.
+

data/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+GlobiGuard Ruby SDK changes should avoid gem runtime dependencies unless a security review accepts a specific exception.
+
+## Validate locally
+
+```bash
+ruby -c lib/globiguard.rb
+ruby test/smoke_test.rb
+gem build globiguard.gemspec
+```
+
+Examples must use placeholder secrets only and webhook handlers must pass raw request body bytes into verification.
+

data/LICENSE

@@ -0,0 +1,106 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity exercising
+      permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship, whether in Source or Object
+      form, made available under the License.
+
+      "Derivative Works" shall mean any work that is based on (or derived
+      from) the Work and for which the editorial revisions represent an
+      original work of authorship.
+
+      "Contribution" shall mean any work of authorship that is submitted
+      to, included in, or in any way used by Licensor, or incorporated
+      into, the Work.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of, publicly
+      display, publicly perform, sublicense, and distribute the Work and
+      such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to Licensor shall be under the terms and conditions of
+      this License, without any limitation.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor
+      or its Subsidiaries or Licensors, except as required for reasonable
+      and customary use in describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS-IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+      or implied, including, without limitation, any warranties or
+      conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS
+      FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License.
+
+END OF TERMS AND CONDITIONS

data/README.md

@@ -0,0 +1,46 @@
+# globiguard-ruby
+
+Official dependency-minimal Ruby SDK for GlobiGuard.
+
+The package has no gem runtime dependencies. It uses Ruby stdlib for HTTP, HMAC, JSON, URL handling, and OpenSSL-backed Ed25519 entitlement verification where the installed Ruby/OpenSSL build supports Ed25519.
+
+## Install
+
+```bash
+gem install globiguard
+```
+
+## Server client
+
+```ruby
+require "globiguard"
+
+client = GlobiGuard::Client.server(
+  environment: "sandbox",
+  services: { "controlPlane" => "https://api.globiguard.com" },
+  credential: GlobiGuard::Credential.secret("proj_example", "ggsk_example_replace_me", "sandbox")
+)
+
+decision = client.governed_actions.authorize_action_or_throw(
+  actionType: "refund",
+  actor: { id: "user_123" },
+  target: { id: "order_456" }
+)
+```
+
+## Webhooks
+
+Pass the exact raw request body string. Do not parse and re-serialize JSON before verification.
+
+```ruby
+result = GlobiGuard::TrustWebhook.verify(headers, raw_body, "whsec_example_replace_me")
+raise result[:error] unless result[:ok]
+```
+
+## Development
+
+```bash
+ruby -c lib/globiguard.rb
+ruby test/smoke_test.rb
+gem build globiguard.gemspec
+```

data/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+Report suspected vulnerabilities privately through GitHub security advisories for `globiguard/globiguard-ruby`.
+
+## Supported versions
+
+The `0.x` series receives security fixes while the SDK surface is stabilizing.
+
+## Security expectations
+
+- Do not log secret keys, webhook secrets, raw entitlement signing keys, or raw webhook bodies that may contain sensitive data.
+- Always verify trust webhooks against the exact raw request body bytes.
+- Use `sandbox` for tests and `live` only for production credentials issued by the GlobiGuard app.
+- Keep gem runtime dependencies at zero unless a reviewed security need outweighs the supply-chain cost.
+

data/lib/globiguard.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module GlobiGuard
+  VERSION = "0.1.0"
+  ENVIRONMENTS = %w[local sandbox live].freeze
+
+  Credential = Struct.new(:kind, :project_id, :token, :environment, keyword_init: true) do
+    def self.secret(project_id, token, environment)
+      new(kind: "secret", project_id: project_id, token: token, environment: environment)
+    end
+
+    def self.publishable(project_id, token, environment)
+      new(kind: "publishable", project_id: project_id, token: token, environment: environment)
+    end
+
+    def self.local(token = nil)
+      new(kind: "local", project_id: nil, token: token, environment: "local")
+    end
+  end
+
+  class Client
+    attr_reader :transport
+
+    def self.server(environment:, services:, credential:)
+      raise ArgumentError, "Server clients require secret or local credentials." if credential.kind == "publishable"
+      new(environment: environment, services: services, credential: credential)
+    end
+
+    def self.browser(environment:, services:, credential:)
+      raise ArgumentError, "Browser clients cannot use secret credentials." if credential.kind == "secret"
+      new(environment: environment, services: services, credential: credential)
+    end
+
+    def initialize(environment:, services:, credential:)
+      @transport = Transport.new(environment: environment, services: services, credential: credential)
+    end
+
+    def actions = ResourceClient.new(@transport, "/v1/actions")
+    def audit = ResourceClient.new(@transport, "/v1/audit")
+    def installs = ResourceClient.new(@transport, "/v1/installs")
+    def orgs = ResourceClient.new(@transport, "/v1/orgs")
+    def policies = ResourceClient.new(@transport, "/v1/policies")
+    def queue = ResourceClient.new(@transport, "/v1/queue")
+    def workflows = ResourceClient.new(@transport, "/v1/workflows")
+    def governed_actions = GovernedActions.new(@transport)
+  end
+
+  class Transport
+    RESERVED_HEADERS = %w[
+      x-globiguard-project-id
+      x-globiguard-secret-key
+      x-globiguard-publishable-key
+      x-globiguard-local-mode
+      x-globiguard-local-token
+      x-globiguard-client
+      x-globiguard-environment
+    ].freeze
+
+    def initialize(environment:, services:, credential:)
+      raise ArgumentError, "Environment must be local, sandbox, or live." unless ENVIRONMENTS.include?(environment)
+      raise ArgumentError, "Credential environment must match client environment." unless credential.environment == environment
+
+      @environment = environment
+      @services = services
+      @credential = credential
+      @base_uri = URI(services.fetch("controlPlane"))
+      raise ArgumentError, "HTTPS is required outside local." if environment != "local" && @base_uri.scheme != "https"
+      if credential.kind == "local" && !%w[localhost 127.0.0.1 ::1].include?(@base_uri.host)
+        raise ArgumentError, "Local credentials require localhost or loopback URLs."
+      end
+    end
+
+    def request(method, path, body: nil, headers: {})
+      self.class.validate_path(path)
+      headers.each_key do |name|
+        raise ArgumentError, "Reserved GlobiGuard header cannot be overridden: #{name}" if RESERVED_HEADERS.include?(name.downcase)
+      end
+
+      uri = URI(@base_uri.to_s.sub(%r{/+\z}, "") + path)
+      request = Net::HTTP.const_get(method.capitalize).new(uri)
+      auth_headers.merge(headers).each { |name, value| request[name] = value }
+      request["content-type"] = "application/json" if body
+      request.body = JSON.generate(body) if body
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", read_timeout: 30, open_timeout: 30) do |http|
+        http.request(request)
+      end
+      raise "GlobiGuard request failed with #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+      response.body.nil? || response.body.empty? ? {} : JSON.parse(response.body)
+    end
+
+    def auth_headers
+      headers = {
+        "x-globiguard-client" => "globiguard-ruby/#{VERSION}",
+        "x-globiguard-environment" => @environment
+      }
+      if @credential.kind == "local"
+        headers["x-globiguard-local-mode"] = "true"
+        headers["x-globiguard-local-token"] = @credential.token if @credential.token && !@credential.token.empty?
+      else
+        headers["x-globiguard-project-id"] = require_value(@credential.project_id, "project id")
+        headers[@credential.kind == "secret" ? "x-globiguard-secret-key" : "x-globiguard-publishable-key"] = require_value(@credential.token, "credential token")
+      end
+      headers
+    end
+
+    def self.validate_path(path)
+      raise ArgumentError, "Request path must start with /." unless path.start_with?("/")
+      if path.start_with?("//") || path.include?("\\") || path.include?("?") || path.include?("#") || path.match?(/%(?![0-9A-Fa-f]{2})/)
+        raise ArgumentError, "Unsafe request path."
+      end
+      raise ArgumentError, "Absolute request paths are not allowed." if URI(path).absolute?
+      raise ArgumentError, "Dot segments are not allowed." if path.split("/").any? { |segment| segment == "." || segment == ".." }
+    end
+
+    private
+
+    def require_value(value, label)
+      raise ArgumentError, "Missing #{label}." if value.nil? || value.empty?
+      value
+    end
+  end
+
+  class ResourceClient
+    def initialize(transport, base_path)
+      @transport = transport
+      @base_path = base_path
+    end
+
+    def list = @transport.request("get", @base_path)
+    def get(id) = @transport.request("get", "#{@base_path}/#{URI.encode_www_form_component(id)}")
+    def create(body) = @transport.request("post", @base_path, body: body)
+    def post(suffix, body) = @transport.request("post", "#{@base_path}/#{URI.encode_www_form_component(suffix.sub(%r{\A/+}, ""))}", body: body)
+  end
+
+  class GovernedActions
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def authorize_action_or_throw(body, idempotency_key: nil, correlation_id: nil)
+      headers = {}
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      headers["x-correlation-id"] = correlation_id if correlation_id
+      result = @transport.request("post", "/v1/actions/authorize", body: body, headers: headers)
+      raise "GlobiGuard blocked the governed action." if result["decision"] == "BLOCK"
+      result
+    end
+  end
+
+  module TrustWebhook
+    module_function
+
+    def verify(headers, raw_body, signing_secret, tolerance_seconds: 300)
+      normalized = headers.transform_keys { |key| key.to_s.downcase }
+      delivery = normalized["x-globiguard-delivery-id"]
+      timestamp = normalized["x-globiguard-timestamp"]
+      event_type = normalized["x-globiguard-event-type"]
+      signature = normalized["x-globiguard-signature"]
+      return { ok: false, error: "Missing required webhook headers." } unless delivery && timestamp && event_type && signature
+      return { ok: false, error: "Webhook timestamp is outside the replay window." } if (Time.now.to_i - timestamp.to_i).abs > tolerance_seconds
+
+      signed = "globiguard-hmac-sha256-v1.#{delivery}.#{timestamp}.#{event_type}.#{raw_body}"
+      expected = "v1=#{OpenSSL::HMAC.hexdigest("SHA256", signing_secret, signed)}"
+      return { ok: false, error: "Invalid webhook signature." } unless secure_compare(expected, signature)
+
+      { ok: true, envelope: JSON.parse(raw_body) }
+    end
+
+    def secure_compare(left, right)
+      return false unless left.bytesize == right.bytesize
+      left.bytes.zip(right.bytes).reduce(0) { |memo, pair| memo | (pair[0] ^ pair[1]) }.zero?
+    end
+  end
+
+  module Bootstrap
+    module_function
+
+    def install_registration(profile, package_name:, package_version:, integration_kind:, runtime_kind:)
+      validate_profile(profile)
+      {
+        environment: profile.fetch(:environment),
+        deploymentMode: profile.fetch(:deploymentMode),
+        issuerMode: profile.fetch(:issuerMode),
+        installReporting: profile.fetch(:installReporting),
+        installLabel: profile[:installLabel],
+        package: { name: package_name, version: package_version },
+        integration: { kind: integration_kind, runtime: runtime_kind }
+      }
+    end
+
+    def validate_profile(profile)
+      raise ArgumentError, "Invalid environment." unless ENVIRONMENTS.include?(profile[:environment])
+      if profile[:deploymentMode] == "hosted" && profile[:issuerMode] != "globiguard_issued"
+        raise ArgumentError, "Hosted deployments require globiguard_issued issuer mode."
+      end
+      return unless %w[self_hosted sovereign].include?(profile[:deploymentMode])
+
+      raise ArgumentError, "Self-hosted and sovereign deployments require customer_issued issuer mode." unless profile[:issuerMode] == "customer_issued"
+      raise ArgumentError, "Self-hosted and sovereign install reporting must be opt_in or disabled." unless %w[opt_in disabled].include?(profile[:installReporting])
+    end
+  end
+
+  module Entitlements
+    module_function
+
+    def verify_signed_manifest(compact_jws, public_keys_by_id:)
+      parts = compact_jws.split(".")
+      raise ArgumentError, "Entitlement manifest must be compact JWS." unless parts.length == 3
+      header = JSON.parse(base64url_decode(parts[0]))
+      raise ArgumentError, "Entitlement manifest must use EdDSA." unless header["alg"] == "EdDSA"
+      public_key = public_keys_by_id.fetch(header.fetch("kid"))
+      signing_input = "#{parts[0]}.#{parts[1]}"
+      signature = base64url_decode(parts[2])
+      verify_ed25519!(base64url_decode(public_key), signing_input, signature)
+      payload = JSON.parse(base64url_decode(parts[1]))
+      raise ArgumentError, "Unsupported entitlement manifest schema." unless payload["schema"] == "globiguard.entitlement_manifest.v1"
+      now = Time.now.to_i
+      raise ArgumentError, "Entitlement manifest is not active yet." if payload["nbf"] && payload["nbf"].to_i > now
+      raise ArgumentError, "Entitlement manifest is expired." if payload["exp"] && payload["exp"].to_i <= now
+      payload
+    end
+
+    def verify_ed25519!(raw_public_key, signing_input, signature)
+      prefix = [48, 42, 48, 5, 6, 3, 43, 101, 112, 3, 33, 0].pack("C*")
+      key = OpenSSL::PKey.read(prefix + raw_public_key)
+      verified = key.verify(nil, signature, signing_input)
+      raise OpenSSL::PKey::PKeyError, "Invalid entitlement manifest signature." unless verified
+    rescue NoMethodError, OpenSSL::PKey::PKeyError => e
+      raise OpenSSL::PKey::PKeyError, "Ruby/OpenSSL Ed25519 verification is unavailable or failed: #{e.message}"
+    end
+
+    def base64url_decode(value)
+      Base64.urlsafe_decode64(value + ("=" * ((4 - value.length % 4) % 4)))
+    end
+  end
+end
+

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: globiguard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GlobiGuard
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-29 00:00:00.000000000 Z
+dependencies: []
+description: Dependency-minimal Ruby SDK for GlobiGuard trusted access workflows.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- lib/globiguard.rb
+homepage: https://globiguard.com
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://globiguard.com
+  source_code_uri: https://github.com/globiguard/globiguard-ruby
+  bug_tracker_uri: https://github.com/globiguard/globiguard-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official dependency-minimal Ruby SDK for GlobiGuard.
+test_files: []