globiguard 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfe6ca1d82d5c27cd8b501fbf9306911785035cd09384c41e081e1c286cac576
-  data.tar.gz: ae191efdeca8f3ca701fdfd999878bdb46e60e1ca473e87db8af0d997a678957
+  metadata.gz: 6a0b4507bcc2fe64c1b8437f9b7c8db800c3e64bd4dd76f4919f42e95185dd8b
+  data.tar.gz: a5e52803a7fc11a6abe086a8704331922597170be3bf6f5bddbc654494488562
 SHA512:
-  metadata.gz: 698b401af1ea2603753d2d99093bfc559a87b5c0b02ca30a5e59c0cb071f3a088d10ab2849a86d976fffcb35fc2049fb96d7896b88d72aaf96fd12492d1d0cd9
-  data.tar.gz: c0dd8138ca55a3575ab55df1e829a0660caf014ef09ff42e15639dc9c98d5f47b3c9072d015b2cdf054d501c40a706852b64db6de751d7bcfa1d0db8a4e07694
+  metadata.gz: f0791129522cb195a6c654fc9c4a23888b52c286247a618a83e03b765818bee657479b00ab5b600054ba3298023f4266869aa3f301f97e298405ba8d248a7329
+  data.tar.gz: 3e01b131159716c7f96e7950b57ce930fe86d15972c5b2a473fa989c14350454c35aea030b053f0d903b2440a62572564d905a57ba40c7cc32d37ebefbcb9963

data/CHANGELOG.md

@@ -1,6 +1,13 @@
-# Changelog
-
-## 0.1.0
+# Changelog
+
+## 0.2.0
+
+- Tightened governed-action execution so only a current, obligation-free
+  `ALLOW` decision is executable.
+- Added regression coverage for `MODIFY`, queued approvals, and other
+  non-executable decisions.
+
+## 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/README.md

@@ -21,12 +21,30 @@ client = GlobiGuard::Client.server(
   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" }
-)
-```
+decision = client.governed_actions.authorize_action_or_throw(
+  context: {
+    actionType: "refund.create",
+    destination: {
+      type: "custom",
+      name: "payments-production"
+    },
+    dataClasses: ["CONFIDENTIAL"],
+    actor: {
+      id: "support-agent-123",
+      type: "agent"
+    },
+    purpose: "Resolve an approved customer escalation",
+    correlationId: "case_456",
+    idempotencyKey: "case_456:refund:v1"
+  }
+)
+```
+
+The governed client includes approval polling, queue review, evidence export,
+evidence-package summaries, and incident replay. Only a current, short-lived,
+obligation-free `ALLOW` explicitly authorizes the exact action once. `MODIFY`,
+`QUEUE`, `BLOCK`, dry-run, expired, and incomplete responses stop the
+authorize-or-throw path before a downstream action runs.
 
 ## Webhooks
 

data/lib/globiguard.rb

@@ -28,28 +28,29 @@ module GlobiGuard
   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)
+    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, read_only: false)
     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)
+    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, read_only: true)
+    end
+
+    def initialize(environment:, services:, credential:, read_only:)
+      @transport = Transport.new(environment: environment, services: services, credential: credential)
+      @read_only = read_only
+    end
+
+    def actions = ResourceClient.new(@transport, "/v1/actions", read_only: @read_only)
+    def audit = ResourceClient.new(@transport, "/v1/audit", read_only: @read_only)
+    def installs = ResourceClient.new(@transport, "/v1/installs", read_only: @read_only)
+    def orgs = ResourceClient.new(@transport, "/v1/orgs", read_only: @read_only)
+    def policies = ResourceClient.new(@transport, "/v1/policies", read_only: @read_only)
+    def queue = ResourceClient.new(@transport, "/v1/queue", read_only: @read_only)
+    def workflows = ResourceClient.new(@transport, "/v1/workflows", read_only: @read_only)
+    def governed_actions = GovernedActions.new(@transport, read_only: @read_only)
   end
 
   class Transport
@@ -77,13 +78,15 @@ module GlobiGuard
       end
     end
 
-    def request(method, path, body: nil, headers: {})
-      self.class.validate_path(path)
+    def request(method, path, body: nil, headers: {}, query: {})
+      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)
+      uri = URI(@base_uri.to_s.sub(%r{/+\z}, "") + path)
+      filtered_query = query.reject { |_key, value| value.nil? || value.to_s.empty? }
+      uri.query = URI.encode_www_form(filtered_query) unless filtered_query.empty?
       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
@@ -113,11 +116,15 @@ module GlobiGuard
 
     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 == ".." }
+      if path.start_with?("//") || path.include?("//") || 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?
+      unsafe_segment = path.split("/").any? do |segment|
+        decoded = URI.decode_www_form_component(segment)
+        decoded == "." || decoded == ".." || decoded.include?("/") || decoded.include?("\\")
+      end
+      raise ArgumentError, "Encoded separators and dot segments are not allowed." if unsafe_segment
     end
 
     private
@@ -128,31 +135,166 @@ module GlobiGuard
     end
   end
 
-  class ResourceClient
-    def initialize(transport, base_path)
-      @transport = transport
-      @base_path = base_path
+  class ResourceClient
+    def initialize(transport, base_path, read_only:)
+      @transport = transport
+      @base_path = base_path
+      @read_only = read_only
     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
+    def create(body)
+      require_write!("Resource creation")
+      @transport.request("post", @base_path, body: body)
+    end
+
+    def post(suffix, body)
+      require_write!("Resource mutation")
+      @transport.request("post", "#{@base_path}/#{URI.encode_www_form_component(suffix.sub(%r{\A/+}, ""))}", body: body)
+    end
+
+    private
+
+    def require_write!(operation)
+      raise ArgumentError, "#{operation} requires a server client." if @read_only
+    end
+  end
+
+  class GovernedActions
+    def initialize(transport, read_only:)
+      @transport = transport
+      @read_only = read_only
     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
+    def authorize_action(body)
+      require_write!("Action authorization")
+      @transport.request("post", "/v1/actions/authorize", body: body)
+    end
+
+    def authorize_action_or_throw(body)
+      result = authorize_action(body)
+      decision = result["decision"]
+      if decision == "ALLOW"
+        raise "A dry-run decision is not an execution permit." if body[:dryRun] == true || body["dryRun"] == true
+        unless result["executable"] == true && result["nextAction"] == "EXECUTE_EXACT_ACTION_ONCE"
+          raise "The control plane marked this response as non-executable."
+        end
+        unless %w[NOT_REQUIRED APPROVED].include?(result["approvalState"])
+          raise "Resolve review and reauthorize before execution."
+        end
+        expires_at = begin
+          Time.iso8601(result["expiresAt"])
+        rescue ArgumentError, TypeError
+          nil
+        end
+        if expires_at.nil? || expires_at <= Time.now || expires_at - Time.now > 300
+          raise "Execution authority must have a current, bounded expiry."
+        end
+        if result["obligations"].is_a?(Array) && !result["obligations"].empty?
+          raise "Enforce all obligations and reauthorize before execution."
+        end
+        if result["modifications"].is_a?(Hash) && !result["modifications"].empty?
+          raise "Apply all modifications and reauthorize before execution."
+        end
+        return result
+      end
+      if decision == "MODIFY"
+        raise "Apply modifications and reauthorize the exact resulting action before execution."
+      end
+      raise "GlobiGuard blocked the governed action." if decision == "BLOCK"
+      if decision == "QUEUE"
+        raise "GlobiGuard queued the governed action for review; do not perform the downstream business action yet."
+      end
+      raise "GlobiGuard returned an unsupported decision; do not perform the downstream business action."
+    end
+
+    def request_approval(body)
+      require_write!("Approval creation")
+      @transport.request("post", "/v1/actions/approvals", body: body)
+    end
+
+    def approval_status(approval_id)
+      @transport.request("get", "/v1/actions/approvals/#{path_segment(approval_id)}")
+    end
+
+    def evidence_references(authorization_id: nil, approval_id: nil, workflow_run_id: nil)
+      @transport.request(
+        "get",
+        "/v1/actions/evidence",
+        query: {
+          authorizationId: authorization_id,
+          approvalId: approval_id,
+          workflowRunId: workflow_run_id
+        }
+      )
+    end
+
+    def export_evidence_package(body = {})
+      require_write!("Evidence export")
+      @transport.request("post", "/v1/audit/export", body: body)
+    end
+
+    def evidence_package_summary(evidence_package_id)
+      @transport.request(
+        "get",
+        "/v1/audit/evidence-packages/#{path_segment(evidence_package_id)}/summary"
+      )
+    end
+
+    def incident_replay(lookup_kind, lookup_id)
+      allowed = %w[workflowRunId correlationId queueEntryId auditEventId authorizationId]
+      raise ArgumentError, "Unsupported incident replay lookup kind." unless allowed.include?(lookup_kind)
+
+      @transport.request(
+        "get",
+        "/v1/audit/incident-replay",
+        query: { lookup_kind => lookup_id }
+      )
+    end
+
+    def review_queue(queue_entry_id, action, body = {})
+      require_write!("Queue review")
+      allowed = %w[approve reject modify escalate resume]
+      raise ArgumentError, "Unsupported queue review action." unless allowed.include?(action)
+
+      @transport.request(
+        "post",
+        "/v1/queue/#{path_segment(queue_entry_id)}/#{action}",
+        body: body
+      )
+    end
+
+    def wait_for_approval(queue_entry_id, max_attempts: 60, interval_seconds: 1.0)
+      raise ArgumentError, "max_attempts must be at least 1." if max_attempts < 1
+
+      max_attempts.times do |index|
+        entry = @transport.request("get", "/v1/queue/#{path_segment(queue_entry_id)}")
+        status = entry["status"]
+        return entry if %w[APPROVED AUTO_APPROVED RESUMED].include?(status)
+        if %w[REJECTED EXPIRED FAILED].include?(status)
+          raise "Queued action resolved as #{status}; do not perform the downstream business action."
+        end
+        if status == "MODIFIED"
+          raise "The reviewer approved a modified action summary. Rebuild the real payload and request a new authorization before executing it."
+        end
+        unless %w[PENDING ESCALATED].include?(status)
+          raise "GlobiGuard returned an unsupported approval state; the downstream business action remains stopped."
+        end
+        sleep(interval_seconds) if index + 1 < max_attempts
+      end
+      raise "Queued action is still pending; do not perform the downstream business action yet."
+    end
+
+    private
+
+    def require_write!(operation)
+      raise ArgumentError, "#{operation} requires a server client." if @read_only
+    end
+
+    def path_segment(value)
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
   end
 
   module TrustWebhook
@@ -185,15 +327,17 @@ module GlobiGuard
 
     def install_registration(profile, package_name:, package_version:, integration_kind:, runtime_kind:)
       validate_profile(profile)
-      {
-        environment: profile.fetch(:environment),
+      {
+        packageName: package_name,
+        packageVersion: package_version,
+        integrationKind: integration_kind,
+        runtimeKind: runtime_kind,
+        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 }
-      }
+        installLabel: profile[:installLabel]
+      }
     end
 
     def validate_profile(profile)
@@ -208,25 +352,134 @@ module GlobiGuard
     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
+  module Entitlements
+    MANIFEST_TYPE = "globiguard.entitlement.v1"
+
+    module_function
+
+    def verify_signed_manifest(
+      compact_jws,
+      public_keys_by_id:,
+      expected_issuer: nil,
+      expected_org_id: nil,
+      expected_project_id: nil,
+      expected_environment: nil,
+      expected_deployment_mode: nil,
+      now: Time.now
+    )
+      parts = compact_jws.split(".")
+      raise ArgumentError, "Entitlement manifest must be compact JWS." unless parts.length == 3
+      header = decode_object(parts[0], "protected header")
+      unless header["alg"] == "EdDSA" && header["typ"] == MANIFEST_TYPE
+        raise ArgumentError, "Unsupported entitlement manifest protected header."
+      end
+      key_id = required_string(header, "kid")
+      public_key = public_keys_by_id.fetch(key_id) do
+        raise ArgumentError, "Unknown entitlement signing key."
+      end
+      signing_input = "#{parts[0]}.#{parts[1]}"
+      signature = base64url_decode(parts[2])
+      verify_ed25519!(base64url_decode(public_key), signing_input, signature)
+      payload = decode_object(parts[1], "payload")
+      validate_payload(payload)
+
+      issued_at = timestamp(payload, "issuedAt")
+      not_before = timestamp(payload, "notBefore")
+      expires_at = timestamp(payload, "expiresAt")
+      verification_time = now.is_a?(Time) ? now : Time.iso8601(now.to_s)
+      raise ArgumentError, "Entitlement manifest timestamps are inconsistent." if issued_at > expires_at || not_before >= expires_at
+      raise ArgumentError, "Entitlement manifest is not active yet." if not_before > verification_time
+      raise ArgumentError, "Entitlement manifest is expired." if expires_at <= verification_time
+
+      subject = payload.fetch("subject")
+      expect(expected_issuer, payload.fetch("issuer"), "issuer")
+      expect(expected_org_id, subject.fetch("orgId"), "organization")
+      expect(expected_project_id, subject.fetch("projectId"), "project")
+      expect(expected_environment, subject.fetch("environment"), "environment")
+      expect(expected_deployment_mode, subject.fetch("deploymentMode"), "deployment mode")
+      payload
+    rescue Date::Error
+      raise ArgumentError, "Entitlement verification now must be an ISO timestamp."
+    end
+
+    def validate_payload(payload)
+      unless payload["manifestType"] == MANIFEST_TYPE && payload["manifestVersion"] == 1
+        raise ArgumentError, "Unsupported entitlement manifest payload."
+      end
+      %w[manifestId issuer issuedAt notBefore expiresAt].each { |field| required_string(payload, field) }
+
+      subject = required_hash(payload, "subject")
+      %w[orgId workspaceName orgSlug projectId projectSlug].each { |field| required_string(subject, field) }
+      unless %w[sandbox live].include?(required_string(subject, "environment"))
+        raise ArgumentError, "Entitlement manifest subject environment is invalid."
+      end
+      unless %w[self_hosted sovereign].include?(required_string(subject, "deploymentMode"))
+        raise ArgumentError, "Entitlement manifest subject deployment mode is invalid."
+      end
+
+      commercial = required_hash(payload, "commercial")
+      unless %w[FREE STARTER GROWTH SCALE ENTERPRISE].include?(required_string(commercial, "commercialPlan"))
+        raise ArgumentError, "Entitlement manifest commercial plan is invalid."
+      end
+      unless %w[FREE PILOT ACTIVE GRACE PAST_DUE SUSPENDED CANCELED].include?(required_string(commercial, "billingStatus"))
+        raise ArgumentError, "Entitlement manifest billing status is invalid."
+      end
+      unless [true, false].include?(commercial["pilotActive"])
+        raise ArgumentError, "Entitlement manifest pilotActive must be boolean."
+      end
+
+      entitlements = required_hash(payload, "entitlements")
+      nullable_counter(entitlements, "includedQueriesPerMonth")
+      nullable_counter(entitlements, "frameworkSlots")
+      unless %w[NONE METERED CONTRACT].include?(required_string(entitlements, "overageMode"))
+        raise ArgumentError, "Entitlement manifest overage mode is invalid."
+      end
+    end
+
+    def decode_object(encoded, label)
+      value = JSON.parse(base64url_decode(encoded))
+      raise ArgumentError, "Entitlement manifest #{label} must be a JSON object." unless value.is_a?(Hash)
+      value
+    rescue JSON::ParserError, ArgumentError => e
+      raise e if e.message.start_with?("Entitlement manifest")
+      raise ArgumentError, "Invalid entitlement manifest #{label}."
+    end
+
+    def required_hash(parent, field)
+      value = parent[field]
+      raise ArgumentError, "Entitlement manifest field #{field} must be an object." unless value.is_a?(Hash)
+      value
+    end
+
+    def required_string(parent, field)
+      value = parent[field]
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "Entitlement manifest field #{field} must be a non-empty string."
+      end
+      value
+    end
+
+    def timestamp(parent, field)
+      Time.iso8601(required_string(parent, field))
+    rescue ArgumentError => e
+      raise e if e.message.start_with?("Entitlement manifest field")
+      raise ArgumentError, "Entitlement manifest field #{field} must be an ISO timestamp."
+    end
+
+    def nullable_counter(parent, field)
+      raise ArgumentError, "Entitlement manifest field #{field} is required." unless parent.key?(field)
+      value = parent[field]
+      return if value.nil? || (value.is_a?(Integer) && value >= 0)
+      raise ArgumentError, "Entitlement manifest field #{field} must be nil or a non-negative integer."
+    end
+
+    def expect(expected, actual, label)
+      return if expected.nil?
+      expected_digest = OpenSSL::Digest::SHA256.digest(expected.to_s)
+      actual_digest = OpenSSL::Digest::SHA256.digest(actual.to_s)
+      return if OpenSSL.fixed_length_secure_compare(expected_digest, actual_digest)
+      raise ArgumentError, "Entitlement manifest #{label} does not match the expected value."
+    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*")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: globiguard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - GlobiGuard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies: []
 description: Dependency-minimal Ruby SDK for GlobiGuard trusted access workflows.
 email: