ace-hitl 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/.ace-defaults/hitl/config.yml +0 -0
  3. data/.ace-defaults/nav/protocols/skill-sources/ace-hitl.yml +0 -0
  4. data/.ace-defaults/nav/protocols/wfi-sources/ace-hitl.yml +0 -0
  5. data/CHANGELOG.md +20 -0
  6. data/Rakefile +0 -0
  7. data/docs/demo/ace-hitl-scope-and-answer.tape.yml +0 -0
  8. data/docs/demo/fixtures/demo-context.md +0 -0
  9. data/docs/usage.md +47 -2
  10. data/handbook/README.md +0 -0
  11. data/handbook/skills/as-hitl/SKILL.md +0 -0
  12. data/handbook/workflow-instructions/hitl.wf.md +0 -0
  13. data/lib/ace/hitl/atoms/hitl_effect_validator.rb +0 -0
  14. data/lib/ace/hitl/atoms/hitl_file_pattern.rb +0 -0
  15. data/lib/ace/hitl/atoms/hitl_id_formatter.rb +0 -0
  16. data/lib/ace/hitl/cli/commands/create.rb +0 -0
  17. data/lib/ace/hitl/cli/commands/list.rb +0 -0
  18. data/lib/ace/hitl/cli/commands/serve.rb +38 -2
  19. data/lib/ace/hitl/cli/commands/show.rb +0 -0
  20. data/lib/ace/hitl/lifecycle/client.rb +11 -151
  21. data/lib/ace/hitl/lifecycle/credential_path_policy.rb +183 -0
  22. data/lib/ace/hitl/lifecycle/frame_exchange.rb +78 -0
  23. data/lib/ace/hitl/lifecycle/frame_serving.rb +119 -0
  24. data/lib/ace/hitl/lifecycle/lifecycle_requests.rb +101 -0
  25. data/lib/ace/hitl/lifecycle/policy.rb +34 -3
  26. data/lib/ace/hitl/lifecycle/proposals.rb +12 -0
  27. data/lib/ace/hitl/lifecycle/remote_peer.rb +78 -0
  28. data/lib/ace/hitl/lifecycle/service.rb +33 -102
  29. data/lib/ace/hitl/lifecycle/store.rb +1 -0
  30. data/lib/ace/hitl/lifecycle/tls_access_policy.rb +50 -0
  31. data/lib/ace/hitl/lifecycle/tls_authority.rb +121 -0
  32. data/lib/ace/hitl/lifecycle/tls_credentials.rb +210 -0
  33. data/lib/ace/hitl/lifecycle/tls_material.rb +133 -0
  34. data/lib/ace/hitl/lifecycle/tls_project_scope.rb +68 -0
  35. data/lib/ace/hitl/lifecycle/tls_service.rb +242 -0
  36. data/lib/ace/hitl/lifecycle.rb +11 -0
  37. data/lib/ace/hitl/models/hitl_event.rb +0 -0
  38. data/lib/ace/hitl/molecules/hitl_answer_editor.rb +0 -0
  39. data/lib/ace/hitl/molecules/hitl_config_loader.rb +0 -0
  40. data/lib/ace/hitl/molecules/hitl_creator.rb +0 -0
  41. data/lib/ace/hitl/molecules/hitl_display_formatter.rb +0 -0
  42. data/lib/ace/hitl/molecules/hitl_loader.rb +0 -0
  43. data/lib/ace/hitl/molecules/hitl_resolver.rb +0 -0
  44. data/lib/ace/hitl/molecules/hitl_scanner.rb +0 -0
  45. data/lib/ace/hitl/molecules/resume_dispatcher.rb +0 -0
  46. data/lib/ace/hitl/molecules/worktree_scope_resolver.rb +0 -0
  47. data/lib/ace/hitl/proposals/policy.rb +1 -0
  48. data/lib/ace/hitl/providers/lab/assignment_binding.rb +20 -1
  49. data/lib/ace/hitl/version.rb +1 -1
  50. metadata +31 -6
@@ -0,0 +1,242 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "socket"
4
+ require "openssl"
5
+ require_relative "protocol"
6
+ require_relative "store"
7
+ require_relative "otp_vault"
8
+ require_relative "remote_peer"
9
+ require_relative "tls_access_policy"
10
+ require_relative "frame_serving"
11
+ require_relative "tls_project_scope"
12
+
13
+ module Ace
14
+ module Hitl
15
+ module Lifecycle
16
+ # The host/Incus crossing of the scoped store boundary (spec
17
+ # 8xa.t.nh0): the bounded lifecycle framing protocol over mutual
18
+ # TLS 1.3/TCP. One authority serves ONE project on a loopback TCP
19
+ # endpoint where the project's Incus TCP proxy device connects;
20
+ # the proxy performs no TLS termination and is not an identity
21
+ # authority.
22
+ #
23
+ # Every connection is authenticated from the VERIFIED project-
24
+ # scoped client certificate — exactly one allowed URI SAN, the
25
+ # exact configured SHA-256 fingerprint, the configured issuing CA
26
+ # and the clientAuth EKU, all checked BEFORE any lifecycle frame
27
+ # is decoded. TLS failure, EOF, malformed frame or identity
28
+ # mismatch never falls back to Unix, HTTP or unauthenticated TCP.
29
+ class TlsService
30
+ include FrameServing
31
+
32
+ DEFAULT_IDLE_SECONDS = Service::DEFAULT_IDLE_SECONDS
33
+ MAX_CONNECTIONS = Service::MAX_CONNECTIONS
34
+ HANDSHAKE_SECONDS = 10.0
35
+
36
+ def initialize(root:, binding:, project:, credential:, ssl_context:,
37
+ listen: "127.0.0.1", port:, group: Store::DEFAULT_GROUP, vault: nil, logger: nil,
38
+ idle_seconds: DEFAULT_IDLE_SECONDS, proposal_clock: -> { Time.now.utc }, decision_policy: AccessPolicy.new)
39
+ @root = root
40
+ @binding = binding
41
+ @project = TlsCredentials.project_id(project)
42
+ @credential = credential
43
+ @ssl_context = ssl_context
44
+ @listen = listen
45
+ @port = Integer(port)
46
+ @group = group
47
+ @vault = vault || OtpVault::MemoryVault.new
48
+ @logger = logger
49
+ @idle_seconds = idle_seconds
50
+ @proposal_clock = proposal_clock
51
+ @policy = TlsAccessPolicy.new(project: @project, decision_policy: decision_policy)
52
+ @max_connections = MAX_CONNECTIONS
53
+ @connections = 0
54
+ @handler_threads = []
55
+ @handler_sockets = []
56
+ @connections_mutex = Mutex.new
57
+ @stopping = false
58
+ @server = nil
59
+ end
60
+
61
+ attr_reader :port
62
+
63
+ # Serve until #stop. Installs TERM/INT handlers for a clean
64
+ # shutdown that closes the listener.
65
+ def run(on_ready: nil)
66
+ prepare!
67
+ on_ready.call if on_ready
68
+ if Thread.current == Thread.main
69
+ %i[TERM INT].each do |signal|
70
+ trap(signal) { stop }
71
+ end
72
+ end
73
+ loop do
74
+ break if @stopping
75
+
76
+ ready = IO.select([@server], nil, nil, 0.5)
77
+ next unless ready
78
+
79
+ connection = @server.accept
80
+ slot = @connections_mutex.synchronize do
81
+ break nil if @connections >= @max_connections
82
+
83
+ @connections += 1
84
+ end
85
+ if slot.nil?
86
+ begin
87
+ connection.write(Protocol.encode_error(
88
+ TransportError.new("the HITL boundary is at its connection limit; retry shortly")))
89
+ connection.close
90
+ rescue SystemCallError, IOError
91
+ nil
92
+ end
93
+ next
94
+ end
95
+ @connections_mutex.synchronize do
96
+ @handler_sockets << connection
97
+ @handler_threads.reject! { |thread| !thread.alive? }
98
+ thread = Thread.new(connection) do |tcp|
99
+ begin
100
+ serve_tls_connection(tcp)
101
+ ensure
102
+ @connections_mutex.synchronize do
103
+ @connections -= 1
104
+ @handler_sockets.delete(tcp)
105
+ end
106
+ end
107
+ end
108
+ thread.report_on_exception = false
109
+ @handler_threads << thread
110
+ end
111
+ end
112
+ ensure
113
+ shutdown!
114
+ end
115
+
116
+ def stop
117
+ @stopping = true
118
+ end
119
+
120
+ private
121
+
122
+ def prepare!
123
+ begin
124
+ root_store.ensure_layout!
125
+ @server = TCPServer.new(@listen, @port)
126
+ port = @server.addr[1]
127
+ @port = port if port.positive?
128
+ rescue SystemCallError, IOError => e
129
+ raise TransportError, "the HITL TLS boundary cannot bind (#{e.class}: #{e.message})"
130
+ end
131
+ log("serving tls://#{@listen}:#{@port} for project #{@project}")
132
+ end
133
+
134
+ def shutdown!
135
+ stop
136
+ @connections_mutex.synchronize { @handler_sockets.dup }.each { |socket| socket.close rescue nil }
137
+ failures = []
138
+ @connections_mutex.synchronize { @handler_threads.dup }.each do |thread|
139
+ begin
140
+ thread.join
141
+ rescue Exception => error
142
+ failures << error
143
+ end
144
+ end
145
+ begin
146
+ @server&.close
147
+ rescue SystemCallError, IOError
148
+ nil
149
+ end
150
+ log("stopped")
151
+ raise failures.first unless failures.empty?
152
+ end
153
+
154
+ # Handshake with a bounded deadline, then certificate identity
155
+ # authorization. Any failure refuses the connection BEFORE any
156
+ # lifecycle read/write: no frame is written to an unverified
157
+ # peer and the refusal never becomes a fallback.
158
+ def serve_tls_connection(tcp)
159
+ ssl = accept_tls!(tcp)
160
+ serve_connection(ssl)
161
+ rescue TransportError, OpenSSL::SSL::SSLError, SystemCallError, IOError
162
+ # Sanitized refusal only: handshake and identity failures are
163
+ # observability facts, never fallback triggers.
164
+ log("refused an unauthenticated TLS connection")
165
+ tcp.close rescue nil
166
+ end
167
+
168
+ def accept_tls!(tcp)
169
+ ssl = OpenSSL::SSL::SSLSocket.new(tcp, @ssl_context)
170
+ ssl.sync_close = true
171
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + HANDSHAKE_SECONDS
172
+ loop do
173
+ result = ssl.accept_nonblock(exception: false)
174
+ break if result.is_a?(OpenSSL::SSL::SSLSocket)
175
+
176
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
177
+ raise TransportError, "the HITL TLS handshake deadline exceeded" if remaining <= 0
178
+ IO.select([ssl], [ssl], nil, remaining) or
179
+ raise TransportError, "the HITL TLS handshake deadline exceeded"
180
+ end
181
+ ssl
182
+ rescue OpenSSL::SSL::SSLError, SystemCallError, IOError, TransportError
183
+ ssl.close rescue nil
184
+ raise
185
+ end
186
+
187
+ # The verified certificate is the whole identity: CA membership
188
+ # alone (OpenSSL handshake verification) never grants a project.
189
+ def authorize!(ssl)
190
+ verify_handshake!(ssl)
191
+ certificate = ssl.peer_cert
192
+ unless TlsCredentials.valid_time?(certificate)
193
+ raise TransportError, "the peer certificate is outside its validity window"
194
+ end
195
+ unless TlsCredentials.client_auth_eku?(certificate)
196
+ raise TransportError, "the peer certificate lacks the clientAuth EKU"
197
+ end
198
+ TlsCredentials.single_uri_san!(certificate,
199
+ @credential.fetch("allowed_client_uri_san"), "peer")
200
+ fingerprint = TlsCredentials.sha256_fingerprint(certificate)
201
+ unless fingerprint == @credential.fetch("allowed_client_certificate_sha256")
202
+ raise TransportError, "the peer certificate fingerprint does not match the configured pin"
203
+ end
204
+
205
+ RemotePeer.new(project: @project,
206
+ identity: @credential.fetch("allowed_client_uri_san"))
207
+ end
208
+
209
+ def verify_handshake!(ssl)
210
+ result = ssl.verify_result
211
+ return if result == OpenSSL::X509::V_OK
212
+
213
+ raise TransportError, "the peer certificate did not verify (#{result})"
214
+ rescue OpenSSL::SSLError
215
+ raise TransportError, "the peer certificate verification is unavailable"
216
+ end
217
+
218
+ def authenticate!(socket)
219
+ authorize!(socket)
220
+ end
221
+
222
+ def store_for(peer)
223
+ TlsProjectScope.new(
224
+ Store.new(
225
+ root: @root,
226
+ binding: @binding,
227
+ policy: @policy,
228
+ identity: peer,
229
+ vault: @vault,
230
+ proposal_clock: @proposal_clock, stopping: -> { @stopping }, group: @group
231
+ ),
232
+ project: @project
233
+ )
234
+ end
235
+
236
+ def root_store
237
+ Store.new(root: @root, binding: @binding, policy: @policy, group: @group)
238
+ end
239
+ end
240
+ end
241
+ end
242
+ end
@@ -18,7 +18,18 @@ require_relative "lifecycle/effects"
18
18
  require_relative "lifecycle/otp_vault"
19
19
  require_relative "lifecycle/store"
20
20
  require_relative "lifecycle/protocol"
21
+ require_relative "lifecycle/tls_credentials"
22
+ require_relative "lifecycle/credential_path_policy"
23
+ require_relative "lifecycle/tls_material"
24
+ require_relative "lifecycle/remote_peer"
25
+ require_relative "lifecycle/tls_access_policy"
26
+ require_relative "lifecycle/frame_serving"
27
+ require_relative "lifecycle/tls_project_scope"
28
+ require_relative "lifecycle/frame_exchange"
29
+ require_relative "lifecycle/lifecycle_requests"
21
30
  require_relative "lifecycle/client"
22
31
  require_relative "lifecycle/service"
32
+ require_relative "lifecycle/tls_service"
33
+ require_relative "lifecycle/tls_authority"
23
34
  require_relative "lifecycle/duty"
24
35
  require_relative "lifecycle/overseer"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -108,6 +108,7 @@ module Ace
108
108
 
109
109
  def resolve(record, checkpoint:, now:)
110
110
  return record unless record["state"] == "awaiting-decision"
111
+ return record unless record["silence_delegated"] == true
111
112
  return record if timestamp(now) < timestamp(record.fetch("deadline"))
112
113
  valid = checkpoint["schema"] == "ace.hitl.hermes.ingress-checkpoint/v1" &&
113
114
  checkpoint["request"] == record["request_id"] && checkpoint["revision"] == record["revision_id"] &&
@@ -16,9 +16,14 @@ module Ace
16
16
  # authority. Every doubt maps to the classified BindingError —
17
17
  # unknown identity/authority is an error, never permission.
18
18
  class AssignmentBinding < Lifecycle::Binding
19
- def initialize(coordinator: nil, repo_root: nil)
19
+ def initialize(coordinator: nil, repo_root: nil, project: nil, owner_guard: nil)
20
+ unless (project.nil? && owner_guard.nil?) ||
21
+ (project.is_a?(String) && !project.empty? && owner_guard.respond_to?(:call))
22
+ raise ArgumentError, "installed binding needs both a fixed project and its owner guard"
23
+ end
20
24
  @coordinator = coordinator
21
25
  @repo_root = repo_root
26
+ @project, @owner_guard = project, owner_guard
22
27
  end
23
28
 
24
29
  def validate_request(assignment:, attempt:, project:, requester:, caller_pid: nil)
@@ -30,6 +35,7 @@ module Ace
30
35
  # Read-only owner verification can run inside an already-held
31
36
  # assignment exclusion without reacquiring that exclusion.
32
37
  def reverse_address(assignment:, attempt:, project:, caller_pid:)
38
+ verify_selection!(project)
33
39
  unless caller_pid.is_a?(Integer) && caller_pid.positive?
34
40
  raise Lifecycle::BindingError, "kernel requester process identity is unavailable"
35
41
  end
@@ -49,15 +55,26 @@ module Ace
49
55
  unless project.is_a?(String) && !project.empty?
50
56
  raise Lifecycle::BindingError, "proposal requires an explicit project"
51
57
  end
58
+ verify_selection!(project)
52
59
  coordinator.send(:journal_for)
53
60
  end
54
61
 
55
62
  def proposal_projects
63
+ if @project
64
+ verify_selection!(@project)
65
+ return [@project]
66
+ end
56
67
  coordinator.send(:journal_for).proposals.map { |record| record.fetch("project_id") }.uniq.sort
57
68
  end
58
69
 
59
70
  private
60
71
 
72
+ def verify_selection!(project)
73
+ return unless @project
74
+ raise Lifecycle::BindingError, "project differs from installed HITL owner" unless project == @project
75
+ @owner_guard.call
76
+ end
77
+
61
78
  def with_verified(assignment_id, attempt_id, project_id, requester)
62
79
  # ONLY the authority verification is error-mapped: the
63
80
  # caller's transition (answer hand-off, commits, effects)
@@ -66,12 +83,14 @@ module Ace
66
83
  # failure (review 8x327bud). The exclusion still spans the
67
84
  # whole transition, so the phase flag separates the two.
68
85
  verifying = true
86
+ verify_selection!(project_id)
69
87
  coordinator.with_verified_attempt(
70
88
  assignment_id: assignment_id,
71
89
  attempt_id: attempt_id,
72
90
  project_id: project_id,
73
91
  requester: requester
74
92
  ) do |attempt|
93
+ verify_selection!(project_id)
75
94
  verifying = false
76
95
  yield attempt
77
96
  end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Ace
4
4
  module Hitl
5
- VERSION = "0.14.0"
5
+ VERSION = "0.16.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ace-hitl
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.14.0
4
+ version: 0.16.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Michal Czyz
8
8
  bindir: exe
9
9
  cert_chain: []
10
- date: 2026-10-12 00:00:00.000000000 Z
10
+ date: 2026-10-16 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: ace-hitl-contract
@@ -113,28 +113,42 @@ dependencies:
113
113
  requirements:
114
114
  - - "~>"
115
115
  - !ruby/object:Gem::Version
116
- version: '0.67'
116
+ version: '0.70'
117
117
  type: :runtime
118
118
  prerelease: false
119
119
  version_requirements: !ruby/object:Gem::Requirement
120
120
  requirements:
121
121
  - - "~>"
122
122
  - !ruby/object:Gem::Version
123
- version: '0.67'
123
+ version: '0.70'
124
124
  - !ruby/object:Gem::Dependency
125
125
  name: ace-herdr
126
126
  requirement: !ruby/object:Gem::Requirement
127
127
  requirements:
128
128
  - - "~>"
129
129
  - !ruby/object:Gem::Version
130
- version: 0.5.1
130
+ version: '0.6'
131
131
  type: :runtime
132
132
  prerelease: false
133
133
  version_requirements: !ruby/object:Gem::Requirement
134
134
  requirements:
135
135
  - - "~>"
136
136
  - !ruby/object:Gem::Version
137
- version: 0.5.1
137
+ version: '0.6'
138
+ - !ruby/object:Gem::Dependency
139
+ name: ace-runtime
140
+ requirement: !ruby/object:Gem::Requirement
141
+ requirements:
142
+ - - "~>"
143
+ - !ruby/object:Gem::Version
144
+ version: '0.3'
145
+ type: :runtime
146
+ prerelease: false
147
+ version_requirements: !ruby/object:Gem::Requirement
148
+ requirements:
149
+ - - "~>"
150
+ - !ruby/object:Gem::Version
151
+ version: '0.3'
138
152
  description: Provides the dedicated ace-hitl package surface for human in the loop
139
153
  (HITL) semantics and CLI workflows.
140
154
  email:
@@ -184,20 +198,31 @@ files:
184
198
  - lib/ace/hitl/lifecycle/atomic_json.rb
185
199
  - lib/ace/hitl/lifecycle/binding.rb
186
200
  - lib/ace/hitl/lifecycle/client.rb
201
+ - lib/ace/hitl/lifecycle/credential_path_policy.rb
187
202
  - lib/ace/hitl/lifecycle/duty.rb
188
203
  - lib/ace/hitl/lifecycle/effects.rb
189
204
  - lib/ace/hitl/lifecycle/errors.rb
205
+ - lib/ace/hitl/lifecycle/frame_exchange.rb
206
+ - lib/ace/hitl/lifecycle/frame_serving.rb
190
207
  - lib/ace/hitl/lifecycle/identity.rb
191
208
  - lib/ace/hitl/lifecycle/kinds.rb
209
+ - lib/ace/hitl/lifecycle/lifecycle_requests.rb
192
210
  - lib/ace/hitl/lifecycle/otp_vault.rb
193
211
  - lib/ace/hitl/lifecycle/overseer.rb
194
212
  - lib/ace/hitl/lifecycle/peer.rb
195
213
  - lib/ace/hitl/lifecycle/policy.rb
196
214
  - lib/ace/hitl/lifecycle/proposals.rb
197
215
  - lib/ace/hitl/lifecycle/protocol.rb
216
+ - lib/ace/hitl/lifecycle/remote_peer.rb
198
217
  - lib/ace/hitl/lifecycle/service.rb
199
218
  - lib/ace/hitl/lifecycle/service_publication_binding.rb
200
219
  - lib/ace/hitl/lifecycle/store.rb
220
+ - lib/ace/hitl/lifecycle/tls_access_policy.rb
221
+ - lib/ace/hitl/lifecycle/tls_authority.rb
222
+ - lib/ace/hitl/lifecycle/tls_credentials.rb
223
+ - lib/ace/hitl/lifecycle/tls_material.rb
224
+ - lib/ace/hitl/lifecycle/tls_project_scope.rb
225
+ - lib/ace/hitl/lifecycle/tls_service.rb
201
226
  - lib/ace/hitl/live_client.rb
202
227
  - lib/ace/hitl/models/hitl_event.rb
203
228
  - lib/ace/hitl/molecules/hitl_answer_editor.rb