cloakapi 1.4.1-x86_64-linux

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 (45) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +160 -0
  3. data/LICENSE +202 -0
  4. data/NOTICE +18 -0
  5. data/README.md +407 -0
  6. data/THIRD-PARTY-NOTICES.md +22 -0
  7. data/TRADEMARKS.md +19 -0
  8. data/examples/fake_gateway.rb +78 -0
  9. data/examples/hello.rb +64 -0
  10. data/lib/cloakapi/_lib/linux-x86_64/libcloak_engine.so +0 -0
  11. data/lib/cloakapi/client.rb +1272 -0
  12. data/lib/cloakapi/degraded.rb +77 -0
  13. data/lib/cloakapi/disclosure.rb +252 -0
  14. data/lib/cloakapi/engine.rb +702 -0
  15. data/lib/cloakapi/errors.rb +65 -0
  16. data/lib/cloakapi/pii/bundled_rules.rb +670 -0
  17. data/lib/cloakapi/pii/card_spans.rb +300 -0
  18. data/lib/cloakapi/pii/detector.rb +1925 -0
  19. data/lib/cloakapi/pii/patterns.json +2238 -0
  20. data/lib/cloakapi/pii/pii_match.rb +7 -0
  21. data/lib/cloakapi/pii/pii_type.rb +7 -0
  22. data/lib/cloakapi/pii/ruleset.rb +65 -0
  23. data/lib/cloakapi/pii/tokenizer.rb +411 -0
  24. data/lib/cloakapi/posture.rb +82 -0
  25. data/lib/cloakapi/receipts.rb +406 -0
  26. data/lib/cloakapi/resources/chat.rb +82 -0
  27. data/lib/cloakapi/resources/messages.rb +90 -0
  28. data/lib/cloakapi/resources/models.rb +25 -0
  29. data/lib/cloakapi/resources/receipts.rb +162 -0
  30. data/lib/cloakapi/resources/reconstruct.rb +120 -0
  31. data/lib/cloakapi/resources/request_strings.rb +485 -0
  32. data/lib/cloakapi/resources/reviewable.rb +163 -0
  33. data/lib/cloakapi/resources/tokens.rb +28 -0
  34. data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
  35. data/lib/cloakapi/routing.rb +500 -0
  36. data/lib/cloakapi/streaming.rb +196 -0
  37. data/lib/cloakapi/surrogate_mode.rb +233 -0
  38. data/lib/cloakapi/version.rb +15 -0
  39. data/lib/cloakapi/warnings.rb +137 -0
  40. data/lib/cloakapi.rb +37 -0
  41. data/licenses/Apache-2.0.txt +202 -0
  42. data/licenses/CC-BY-4.0.txt +104 -0
  43. data/licenses/MIT-Faker.txt +21 -0
  44. data/licenses/MIT.txt +21 -0
  45. metadata +150 -0
@@ -0,0 +1,1272 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+ require "uri"
5
+ require "json"
6
+ require "time"
7
+ require "openssl" # §Q45 — HMAC-SHA256 for client-side end-user tokenisation.
8
+ require "digest"
9
+ require "monitor"
10
+
11
+ require_relative "warnings"
12
+
13
+ module CloakAPI
14
+ class Client
15
+ DEFAULT_BASE_URL = "https://api.cloakapi.io"
16
+ SDK_VERSION = CloakAPI::VERSION
17
+
18
+ # SAK 452 (2026-08-10) — wire-headeren som ber MODUSVALET til gatewayen.
19
+ # Speglar `sdk/php` H_PRIVACY_TIER, `sdk/go` headerPrivacyTier,
20
+ # `sdk/java` HEADER_PRIVACY_TIER, `sdk/dotnet` PrivacyTierHeader og
21
+ # `sdk/rust` HEADER_PRIVACY_TIER. Sjå #build_request.
22
+ HEADER_PRIVACY_TIER = "X-CloakAPI-Mode" # F22 / Decision 11e
23
+
24
+ # LEVEL-1-ONLY STRICT FLIP (DECISIONS.md 2026-07-12 + STRICT-FLIP-SURFACE-AUDIT).
25
+ # The gateway is FAIL-CLOSED: it REJECTS any content-relay call
26
+ # (/api/v1/messages, /api/v1/chat/completions) that cannot PROVE it was
27
+ # tokenised on-device. Proof = the pre-tokenised passthrough — a per-body MAC
28
+ # minted by POST /api/v1/pretokenised/mac, relayed as X-Cloak-Client-MAC
29
+ # alongside X-Cloak-Pretokenised: 1, on top of the X-Cloak-Engine-* identity
30
+ # headers (EnforceEngineFloor). The SDK does NOT hold the tenant HMAC key; it
31
+ # asks the gateway to MAC the EXACT egressing bytes under the caller's own API
32
+ # key. Mirrors the Go/Rust/Python/TypeScript SDKs byte-for-behaviour.
33
+ PRETOKENISED_MAC_PATH = "/api/v1/pretokenised/mac"
34
+ CONTENT_RELAY_PATHS = ["/api/v1/messages", "/api/v1/chat/completions"].freeze
35
+
36
+ # Immutable review objects deliberately keep request bytes private. Only the
37
+ # issuing client can turn a preview into a one-use send capability.
38
+ #
39
+ # The step form of the review pattern:
40
+ #
41
+ # prepared = client.messages.prepare(model: ..., messages: ...)
42
+ # prepared.text # the exact outgoing body
43
+ # prepared.coverage # "full", "rules_and_names" or "rules_only"
44
+ # prepared.warnings # Array of CloakAPI::SendWarning
45
+ # prepared.state # "ok" or "degraded"
46
+ # approved = client.approve(prepared) # or prepared.approve
47
+ # reply = client.messages.create(approved)
48
+ class PreparedRequest
49
+ attr_reader :coverage, :warnings
50
+
51
+ def initialize(client, path, raw, token_map, streaming, headers, engine_identity = nil,
52
+ coverage: CloakAPI::Coverage::RULES_ONLY, warnings: [])
53
+ @client, @path, @raw = client, path.freeze, raw.b.freeze
54
+ @digest = Digest::SHA256.hexdigest(@raw).freeze
55
+ @token_map, @streaming = token_map.dup.freeze, streaming
56
+ @headers = headers.transform_keys(&:to_s).transform_values { |value| value.to_s.freeze }.freeze
57
+ @engine_identity = engine_identity&.dup&.freeze
58
+ @coverage = coverage.to_s.freeze
59
+ @warnings = warnings.dup.freeze
60
+ freeze
61
+ end
62
+
63
+ # The exact bytes that will be sent, as text. +preview+ is the older name.
64
+ def text = @raw.dup.force_encoding(Encoding::UTF_8)
65
+ alias preview text
66
+
67
+ def state = @warnings.empty? ? "ok" : "degraded"
68
+ def info = CloakAPI::ReviewInfo.new(state: state, coverage: @coverage, warnings: @warnings)
69
+ def approve = @client.send(:approve_prepared, self)
70
+ def inspect = "#<CloakAPI::PreparedRequest content=redacted>"
71
+ alias to_s inspect
72
+ protected
73
+ attr_reader :path, :raw, :digest, :token_map, :streaming, :headers, :engine_identity
74
+ end
75
+
76
+ class ReviewedRequest
77
+ def initialize(client)
78
+ @client = client
79
+ freeze
80
+ end
81
+ def inspect = "#<CloakAPI::ReviewedRequest content=redacted>"
82
+ alias to_s inspect
83
+ end
84
+
85
+ attr_reader :api_key, :base_url, :max_retries
86
+
87
+ # Keep credentials out of debugger, logger, and pretty-printer output.
88
+ def inspect = "#<CloakAPI::Client api_key=***>"
89
+ alias to_s inspect
90
+
91
+ def pretty_print(pp)
92
+ pp.text(inspect)
93
+ end
94
+
95
+ # GATEWAY-LOCK (feedback_cloakapi_no_free_relay): enforce the HARD billing
96
+ # invariant on the base URL. Mirrors packages/cloak-proxy validate_gateway_base
97
+ # and the TS/Python/Go/Rust/PHP locks — every SDK call MUST flow through the
98
+ # CloakAPI gateway so the markup is charged; there is NO direct-to-provider
99
+ # mode. The base URL must resolve to a CloakAPI gateway host (cloakapi.io /
100
+ # *.cloakapi.io) over https, or to a loopback host (localhost / 127.0.0.0/8 /
101
+ # ::1; http allowed there). Anything else — a raw provider base
102
+ # (api.openai.com, api.x.ai), the userinfo trick (https://cloakapi.io@evil.com),
103
+ # a suffix lookalike (https://cloakapi.io.evil.com), a prefix lookalike
104
+ # (https://notcloakapi.io) or a public plain-http host — is rejected.
105
+ def self.validate_gateway_base(raw)
106
+ # Userinfo, query and fragment are how a copied dashboard URL smuggles a
107
+ # key into the client. Reject them before the value is stored, and do not
108
+ # repeat the caller string in the error.
109
+ text = raw.to_s
110
+ if text.match?(/[[:space:]]/)
111
+ raise ArgumentError, "CloakAPI: invalid base URL"
112
+ end
113
+ trimmed = text.chomp("/")
114
+ uri = begin
115
+ URI.parse(trimmed)
116
+ rescue URI::InvalidURIError
117
+ raise ArgumentError, "CloakAPI: invalid base URL"
118
+ end
119
+ if !uri.user.nil? || !uri.password.nil? || !uri.query.nil? || !uri.fragment.nil?
120
+ raise ArgumentError, "CloakAPI: invalid base URL"
121
+ end
122
+ host = (uri.host || "").downcase.gsub(/\A\[|\]\z/, "") # strip IPv6 brackets
123
+ raise ArgumentError, "CloakAPI: invalid base URL: no host" if host.empty?
124
+
125
+ is_loopback = host == "localhost" || host == "::1" || host.match?(/\A127(?:\.\d{1,3}){3}\z/)
126
+ is_cloakapi = host == "cloakapi.io" || host.end_with?(".cloakapi.io")
127
+ scheme = (uri.scheme || "").downcase
128
+
129
+ if scheme == "https"
130
+ # ok — the only public scheme
131
+ elsif scheme == "http" && is_loopback
132
+ # ok — plain http only for a loopback dev/staging gateway
133
+ else
134
+ raise ArgumentError,
135
+ "CloakAPI: base URL scheme not allowed — use https (plain http is only accepted for loopback dev/staging gateways)"
136
+ end
137
+
138
+ unless is_cloakapi || is_loopback
139
+ raise ArgumentError,
140
+ "CloakAPI is GATEWAY-LOCKED: the base URL must be the CloakAPI gateway or a loopback gateway. " \
141
+ "There is no direct-to-provider mode."
142
+ end
143
+
144
+ trimmed
145
+ end
146
+
147
+ def initialize(api_key = nil, base_url: nil, timeout: 120, max_retries: 3, http: nil, app_id: nil,
148
+ routing: nil, surrogate_mode: nil, end_user_secret: nil, allow_reduced_coverage: true,
149
+ review: nil, strict_coverage: false)
150
+ unless review.nil? || review.respond_to?(:call)
151
+ raise ArgumentError, "review must respond to call(text, info)"
152
+ end
153
+ # The review callback: called with (text, info) before a request is sent
154
+ # by the one-call form of create. Returning a true value approves.
155
+ @review = review
156
+ @api_key = api_key || ENV.fetch("CLOAKAPI_API_KEY", "")
157
+ # §Q45 — HMAC secret for client-side end-user tokenisation. nil uses the API
158
+ # key, so rotating the key rotates the pseudonym; set this to pin one end
159
+ # user to one token across rotations. Must match the other SDKs' value for
160
+ # a cross-language join to line up.
161
+ @end_user_secret = (end_user_secret.nil? || end_user_secret.to_s.empty?) ? nil : end_user_secret
162
+ # C19 client-side routing options (strategy/catalogue/etc); consumed lazily
163
+ # by #router. Empty hash = default passthrough router.
164
+ @routing_options = routing.is_a?(Hash) ? routing : {}
165
+ # GATEWAY-LOCK: the base URL (default or override) can only ever be the
166
+ # CloakAPI gateway or a loopback gateway — never a direct-to-provider base.
167
+ @base_url = self.class.validate_gateway_base(base_url || DEFAULT_BASE_URL).freeze
168
+ @timeout = timeout
169
+ unless max_retries.is_a?(Integer) && max_retries >= 0
170
+ raise ArgumentError, "max_retries must be a non-negative integer"
171
+ end
172
+ @max_retries = max_retries
173
+ origin = URI.parse(@base_url)
174
+ if http && (!http.instance_of?(Net::HTTP) || http.address != origin.host || http.port != origin.port)
175
+ raise ArgumentError, "custom HTTP client must be a plain same-origin Net::HTTP client"
176
+ end
177
+ # Copy only the fixed origin into a fresh private transport. Never retain
178
+ # the caller's client object, middleware, proxy, or later-mutated defaults.
179
+ @http = Net::HTTP.new(origin.host, origin.port)
180
+ @http.use_ssl = origin.scheme == "https" if @http.respond_to?(:use_ssl=)
181
+ @http.open_timeout = 10 if @http.respond_to?(:open_timeout=)
182
+ @http.read_timeout = @timeout if @http.respond_to?(:read_timeout=)
183
+ @http.write_timeout = @timeout if @http.respond_to?(:write_timeout=)
184
+ @http_request = @http.method(:request)
185
+ # ADR-0015 — resolve the attribution app slug (explicit else CLOAK_APP_ID env).
186
+ # Sanitised; nil omits the X-Cloak-App-Id header (builder-account attribution).
187
+ @app_id = self.class.resolve_app_id(app_id)
188
+
189
+ # Level-1-only: CLIENT-SIDE tokenisation is ALWAYS ON (mirrors the
190
+ # Go/Rust/TS/Python SDKs, which have no plaintext tier). The strict gateway
191
+ # rejects any relay that is not client-tokenised + MAC-proven, so raw-by-
192
+ # default is neither offered nor sendable.
193
+ @tokenize = true
194
+ # Session token map (full-token => original) minted this session by the
195
+ # shared engine or the regex fallback, so replies can be de-tokenised.
196
+ # Persists across requests, mirroring the Go client's tokenMap / Python
197
+ # client's _token_map.
198
+ @token_map = {}
199
+ # One re-entrant lock per client. It is held for a whole prepare (every
200
+ # string of one request) and for a whole file tokenisation, so requests
201
+ # that share this client's conversation advance its ledger one at a
202
+ # time, in the order they took the lock, never interleaved.
203
+ @token_mutex = Monitor.new
204
+ # strict_coverage: true is the one explicit option that lets reduced
205
+ # coverage refuse a request. allow_reduced_coverage: false is its older
206
+ # spelling.
207
+ @allow_reduced_coverage = strict_coverage ? false : allow_reduced_coverage
208
+ @last_detection_status = nil
209
+
210
+ # ── SURROGATE MODE (DECISIONS.md Decision 11) ──────────────────────────
211
+ # Exactly two: "balanced" (realistic stand-ins, the DEFAULT) and "max"
212
+ # (opaque <<CLOAK:...>> placeholders). It selects STYLE ONLY — every mode
213
+ # tokenises identically; see CloakAPI::SurrogateMode.
214
+ #
215
+ # An EXPLICIT argument is RESOLVED (a bad literal raises
216
+ # SurrogateMode::Error); nil takes the protected default.
217
+ @surrogate_mode = CloakAPI::SurrogateMode.resolve(surrogate_mode)
218
+
219
+ # THE CONVERSATION LEDGER. Its PRESENCE (even empty) is what puts every
220
+ # tokenise call in CONVERSATION scope, so the same real value keeps the
221
+ # same stand-in for the life of this client — in BOTH modes — and the
222
+ # disclosure may honestly say so. This is the structural guarantee: a
223
+ # ledger with a `claimed` reverse index cannot regress silently, whereas a
224
+ # generator that "happens to be deterministic today" can.
225
+ #
226
+ # RE-IDENTIFICATION MATERIAL: it maps stand-ins back to real values.
227
+ # CLIENT-SIDE ONLY — never egressed, never logged, never in a receipt,
228
+ # exactly like the token map.
229
+ @bindings = {}
230
+ @last_surrogate_mode = nil
231
+ @prepared_requests = {}
232
+ @approved_requests = {}
233
+ @review_mutex = Mutex.new
234
+ end
235
+
236
+ # The surrogate mode every outbound tokenise on this client uses.
237
+ attr_reader :surrogate_mode
238
+
239
+ # The review callback given at construction, or nil.
240
+ attr_reader :review
241
+
242
+ # Approve a prepared request after the application has shown its text.
243
+ # Returns the one-use approved request to pass to +create+.
244
+ def approve(prepared)
245
+ unless prepared.is_a?(PreparedRequest)
246
+ raise CloakAPI::ReviewRequiredError, "explicit review required: approve takes the object returned by prepare"
247
+ end
248
+
249
+ approve_prepared(prepared)
250
+ end
251
+
252
+ # Coverage and warnings of the request an approved object stands for.
253
+ def reviewed_info(reviewed)
254
+ @review_mutex.synchronize do
255
+ entry = @approved_requests[reviewed&.object_id]
256
+ return nil unless entry && entry[:capability].equal?(reviewed)
257
+
258
+ CloakAPI::ReviewInfo.new(state: entry[:warnings].empty? ? "ok" : "degraded",
259
+ coverage: entry[:coverage], warnings: entry[:warnings])
260
+ end
261
+ end
262
+
263
+ # Run +block+ as ONE request on this client's conversation: the lock is
264
+ # held from the first string to the last, and the coverage and warnings of
265
+ # every string tokenised inside are collected for the prepared request.
266
+ def collect_request
267
+ @token_mutex.synchronize do
268
+ outer = @collector
269
+ @collector = { coverage: nil, warnings: [], rules_fallback: false, strings: 0, places: [], media: [] }
270
+ begin
271
+ yield
272
+ @collector
273
+ ensure
274
+ @collector = outer
275
+ end
276
+ end
277
+ end
278
+ private :collect_request
279
+
280
+ # Called while a request is prepared: a kind of place (:number, :media)
281
+ # holds something that is sent as it is. +values+ are the media values
282
+ # themselves, kept only to leave them out of the final local check.
283
+ def note_placement(place, values = [])
284
+ @token_mutex.synchronize do
285
+ next unless @collector
286
+
287
+ @collector[:places] << place unless @collector[:places].include?(place)
288
+ @collector[:media].concat(values) if place == :media
289
+ end
290
+ end
291
+ private :note_placement
292
+
293
+ # What the most recent outbound tokenise pass ACTUALLY did
294
+ # ({CloakAPI::SurrogateMode::Report}), or nil before the first tokenised
295
+ # call. Feed +client.last_surrogate_mode.continuity+ into
296
+ # {CloakAPI::Disclosure.with_disclosure} so the disclosure's claim matches
297
+ # the bytes it is describing.
298
+ def last_surrogate_mode
299
+ @token_mutex.synchronize { @last_surrogate_mode }
300
+ end
301
+
302
+ # Coverage status from the most recent outbound text tokenisation.
303
+ def last_detection_status
304
+ @token_mutex.synchronize { @last_detection_status&.dup }
305
+ end
306
+
307
+ # Whether client-side tokenisation is active (always true under Level-1-only).
308
+ attr_reader :tokenize
309
+
310
+ # Tokenise one outbound string ENTIRELY on-device, ENGINE-FIRST + FAIL-CLOSED
311
+ # (the SDK's one text-tokenise entry point — mirrors Go's tokenizeOutbound /
312
+ # Python tokenize_text(prefer_engine=True)). Minted full-token => original
313
+ # pairs are merged into the session map so the reply can be de-tokenised.
314
+ #
315
+ # PRIMARY: the shared client-side FFI engine (fasit ruleset + checksum
316
+ # validators + native NER) — identical protection to the drop-in proxy,
317
+ # desktop app and every other surface. If the engine is present but REFUSES
318
+ # (EngineError), the error PROPAGATES and the raw text is NEVER sent.
319
+ # FALLBACK: the pure-regex detectors, ONLY when the engine library is absent.
320
+ def tokenize_outbound(text, seed_hex: nil)
321
+ return text if text.nil? || text.to_s.empty?
322
+
323
+ @token_mutex.synchronize do
324
+ # EngineError is intentionally NOT rescued: fail closed.
325
+ # The conversation ledger is passed IN and the advanced ledger stored
326
+ # back, so turn 2 reuses turn 1's stand-ins.
327
+ res = CloakAPI::Pii.tokenize_text_ex(
328
+ text.to_s, existing_map: @token_map, seed_hex: seed_hex,
329
+ mode: @surrogate_mode, bindings: @bindings, accepted: @allow_reduced_coverage
330
+ )
331
+ @token_map = res.token_map
332
+ @bindings = res.bindings.dup
333
+ @last_surrogate_mode = res.surrogate_mode
334
+ @last_detection_status = { coverage: res.coverage, warning: res.warning, degraded: res.degraded }
335
+ if @collector
336
+ @collector[:strings] += 1
337
+ @collector[:coverage] = CloakAPI::Coverage.weakest(@collector[:coverage], res.coverage)
338
+ @collector[:warnings] = CloakAPI::Warnings.merge(@collector[:warnings], res.warnings)
339
+ @collector[:rules_fallback] ||= res.engine != "ffi"
340
+ end
341
+ res.text
342
+ end
343
+ end
344
+
345
+ # A snapshot of the session token map (full-token => original). Used by the
346
+ # streaming detokeniser to restore reply chunks on-device.
347
+ def session_token_map
348
+ @token_mutex.synchronize { @token_map.dup }
349
+ end
350
+
351
+ # Restore originals in a response string using the session map (companion to
352
+ # {#tokenize_outbound} — de-tokenises a model reply on-device).
353
+ def detokenize_text(text, token_map: nil)
354
+ return text unless text.is_a?(String)
355
+ return CloakAPI::Pii.detokenize(text, token_map) if token_map
356
+
357
+ @token_mutex.synchronize { CloakAPI::Pii.detokenize(text, @token_map) }
358
+ end
359
+
360
+ # Tokenise a FILE or IMAGE ENTIRELY on-device (the SDK's file/image entry
361
+ # point — mirrors Python's +tokenize_file+ / TypeScript's +tokenizeFile+).
362
+ #
363
+ # Images (PNG/JPEG/WebP/GIF/BMP/TIFF) are OCR'd on-device; PDF/DOCX/XLSX/
364
+ # PPTX/CSV/HTML/… are extracted and tokenised — the shared engine's one
365
+ # file-pipeline decides by MIME (there is deliberately NO client-side format
366
+ # allowlist that could block an image). The RAW bytes NEVER leave this
367
+ # machine: only the returned +text+ (tokenised Markdown) is meant to egress,
368
+ # and it rides the SAME pre-tokenised-MAC + engine-identity relay path as
369
+ # text — feed +text+ into {#messages}/{#chat} exactly as you would a prompt.
370
+ # The gateway only ever sees surrogate <<CLOAK:…>> tokens.
371
+ #
372
+ # The discovered token => original pairs are MERGED into this client's
373
+ # session map, so a subsequent reply is auto-detokenised by
374
+ # {#detokenize_text} / the resource de-tokenisation.
375
+ #
376
+ # FAIL-CLOSED (the core product invariant): if the client-side engine
377
+ # (+libcloak_engine+) is unavailable this raises +CloakAPI::Engine::EngineError+
378
+ # and NEVER falls back to sending the raw file/image to the gateway. It also
379
+ # propagates +EngineError+ if the engine refuses a file
380
+ # (encrypted/unsupported/undecodable).
381
+ #
382
+ # @param data [String] raw file/image bytes (a binary String)
383
+ # @param mime [String, nil] best-effort MIME hint (e.g. "image/png"); the
384
+ # engine sniffs magic bytes + +filename+ when nil/empty
385
+ # @param filename [String, nil] sharpens type resolution (docx/xlsx/pptx
386
+ # share ZIP magic)
387
+ # @param names [Array<String>, nil] externally-detected PERSON spans folded in
388
+ # @return [Hash] +{ "text" => <tokenised markdown>, "token_map" => {full-token => original}, "meta" => {...} }+
389
+ # @raise [CloakAPI::Engine::EngineError] engine absent (fail-closed) or refusal
390
+ def tokenize_file(data, mime: nil, filename: nil, names: nil)
391
+ engine = begin
392
+ CloakAPI::Engine.get
393
+ rescue StandardError
394
+ nil # load problem -> treated as unavailable -> fail closed below
395
+ end
396
+
397
+ if engine.nil?
398
+ raise CloakAPI::Engine::EngineError,
399
+ "client-side engine (libcloak_engine) not available — refusing to send the raw " \
400
+ "file/image to the gateway. Install the CloakAPI tokeniser engine (or set " \
401
+ "CLOAKAPI_ENGINE_LIB) so files are OCR'd + tokenised fully on-device."
402
+ end
403
+
404
+ # EngineError (present-but-refused) is intentionally NOT rescued: fail closed.
405
+ # Same acceptance as tokenize_outbound. File bytes are not a reason to
406
+ # stop a send: standard mode warns, strict mode is the only refusal.
407
+ accepted = @allow_reduced_coverage
408
+ # The ledger is read, handed to the engine and stored back under ONE lock.
409
+ # Reading it outside the lock let a text call that finished in between be
410
+ # overwritten by this call's older copy.
411
+ @token_mutex.synchronize do
412
+ result = engine.tokenise_file(data, mime: mime, filename: filename, names: names,
413
+ mode: @surrogate_mode, bindings: @bindings, accepted: accepted)
414
+ @token_map = @token_map.merge(result.token_map)
415
+ # Advance the SHARED ledger, so an entity appearing in both a file and
416
+ # the prompt gets ONE stand-in and the next turn keeps it.
417
+ @bindings = result.bindings.dup
418
+ @last_surrogate_mode = result.surrogate_mode
419
+ { "text" => result.markdown, "token_map" => result.token_map.dup, "meta" => result.meta }
420
+ end
421
+ end
422
+
423
+ # ADR-0015 — sanitise an opaque app/site slug for X-Cloak-App-Id: lower-cased,
424
+ # <=64 [a-z0-9._-]. Returns nil for anything invalid/empty (header omitted).
425
+ def self.sanitize_app_id(raw)
426
+ return nil unless raw.is_a?(String)
427
+ slug = raw.strip.downcase
428
+ return nil if slug.empty? || slug.length > 64
429
+ slug.match?(/\A[a-z0-9._-]+\z/) ? slug : nil
430
+ end
431
+
432
+ # ADR-0015 — validate a builder-supplied OPAQUE pseudonymous end-user id for
433
+ # X-Cloak-End-User: <=128 [A-Za-z0-9._:-]. Returns nil for anything
434
+ # invalid/empty (header omitted). SHAPE guard only — never auto-fill from PII.
435
+ #
436
+ # This is DELIBERATELY still a pure shape guard, and it is NOT what decides
437
+ # what goes on the wire — .end_user_header_value is. This comment used to end
438
+ # "the gateway drops PII-shaped values as a fail-safe", which was true and was
439
+ # the whole problem: by the time the gateway drops it the value has already
440
+ # crossed the network, which is sak 181 verbatim.
441
+ def self.sanitize_end_user(raw)
442
+ return nil unless raw.is_a?(String)
443
+ ref = raw.strip
444
+ return nil if ref.empty? || ref.length > 128
445
+ ref.match?(/\A[A-Za-z0-9._:-]+\z/) ? ref : nil
446
+ end
447
+
448
+ # ── KOMITÉ-ORDRE 10 §Q45 (sak 181) — TOKENISE, NEVER REFUSE ──────────────
449
+
450
+ # Prefix marking a DERIVED end-user ref. Identical to the gateway's
451
+ # StableEndUserPseudonym::PREFIX and the TypeScript SDK's
452
+ # END_USER_PSEUDONYM_PREFIX, so all three emit one vocabulary.
453
+ END_USER_PSEUDONYM_PREFIX = "cloak_eu_"
454
+
455
+ # Luhn (mod-10) over a digits-only string.
456
+ def self.luhn_valid?(d)
457
+ sum = 0
458
+ alt = false
459
+ d.each_char.to_a.reverse.each do |ch|
460
+ n = ch.ord - 48
461
+ if alt
462
+ n *= 2
463
+ n -= 9 if n > 9
464
+ end
465
+ sum += n
466
+ alt = !alt
467
+ end
468
+ (sum % 10).zero?
469
+ end
470
+ private_class_method :luhn_valid?
471
+
472
+ # ISO 13616 IBAN structure + mod-97.
473
+ def self.iban_valid?(raw)
474
+ v = raw.gsub(/[.\-:_\s]/, "").upcase
475
+ return false unless v.match?(/\A[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}\z/)
476
+ rem = 0
477
+ (v[4..] + v[0, 4]).each_char do |c|
478
+ part = c.match?(/[A-Z]/) ? (c.ord - 55).to_s : c
479
+ part.each_char { |dch| rem = (rem * 10 + (dch.ord - 48)) % 97 }
480
+ end
481
+ rem == 1
482
+ end
483
+ private_class_method :iban_valid?
484
+
485
+ # US ABA routing checksum (9 digits).
486
+ def self.aba_valid?(d)
487
+ return false unless d.length == 9
488
+ n = d.each_char.map { |c| c.ord - 48 }
489
+ ((3 * (n[0] + n[3] + n[6])) + (7 * (n[1] + n[4] + n[7])) + (n[2] + n[5] + n[8])) % 10 == 0
490
+ end
491
+ private_class_method :aba_valid?
492
+
493
+ # ADR-0015 / §Q45 — structured-PII SHAPE check over a single end-user id, run
494
+ # CLIENT-SIDE, BEFORE the value is put on the wire. Family-for-family
495
+ # identical to the TypeScript SDK's looksLikeEndUserPii and the gateway's
496
+ # UsageAttributionGuard::looksLikePii (card / IBAN / ABA / national-id /
497
+ # phone / BIC), plus EMAIL — which the server-side guard documents as out of
498
+ # scope because "@" cannot survive the opaque charset. True on the wire; not
499
+ # here, where the SDK still sees the value.
500
+ #
501
+ # [0-9] is spelled out rather than \d, because \d differs between regex
502
+ # engines and this predicate has to agree with the TypeScript SDK exactly.
503
+ def self.looks_like_end_user_pii?(value)
504
+ return false unless value.is_a?(String)
505
+ v = value.strip
506
+ return false if v.empty?
507
+
508
+ # Email — reachable here, unreachable server-side (see comment).
509
+ return true if v.match?(/\A[^\s@]+@[^\s@]+\.[A-Za-z]{2,}\z/)
510
+
511
+ digits = v.gsub(/[.\-:_\s()+]/, "")
512
+ all_digits = !digits.empty? && digits.match?(/\A[0-9]+\z/)
513
+
514
+ # Payment card (PAN): 13–19 digits passing Luhn.
515
+ return true if all_digits && digits.length.between?(13, 19) && luhn_valid?(digits)
516
+ # IBAN.
517
+ return true if iban_valid?(v)
518
+ # US ABA routing number.
519
+ return true if all_digits && digits.length == 9 && aba_valid?(digits)
520
+ # US SSN written 3-2-4.
521
+ return true if v.match?(/\A[0-9]{3}-[0-9]{2}-[0-9]{4}\z/)
522
+ # Telephone: 10–15 digits, not all-identical.
523
+ return true if all_digits && digits.length.between?(10, 15) && digits.chars.uniq.length > 1
524
+ # SWIFT/BIC with a digit in the location/branch block.
525
+ return true if v.match?(/\A[A-Za-z]{6}[A-Za-z0-9]{2}([A-Za-z0-9]{3})?\z/) && v.match?(/[0-9]/)
526
+
527
+ false
528
+ end
529
+
530
+ # Derive the opaque token that REPLACES a PII-shaped (or malformed) end-user
531
+ # id before it is sent. HMAC-SHA256 under a caller-held secret, 128 bits of
532
+ # hex, "cloak_eu_"-prefixed — byte-identical to the TypeScript SDK's
533
+ # pseudonymiseEndUser and the gateway's StableEndUserPseudonym, so one end
534
+ # user reads as one vocabulary on every side of the wire.
535
+ #
536
+ # HMAC, not a hash: sha256(email) is stable AND reversible with a wordlist.
537
+ # The secret is the caller's own API key, which CloakAPI does not hold in
538
+ # plaintext, so the derived token is not reversible by us either. Rotating the
539
+ # key rotates the pseudonym; pass end_user_secret: to pin it.
540
+ def self.pseudonymise_end_user(raw, secret)
541
+ msg = raw.strip.downcase
542
+ mac = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, msg)
543
+ END_USER_PSEUDONYM_PREFIX + mac[0, 32]
544
+ end
545
+
546
+ # KOMITÉ-ORDRE 10 §Q45 (sak 181) — TOKENISE, NEVER REFUSE. The single place
547
+ # that decides what X-Cloak-End-User carries.
548
+ #
549
+ # This used to be sanitize_end_user called straight from #end_user_header,
550
+ # which returned nil for anything not already opaque-shaped: a SILENT DROP,
551
+ # client-side, with the builder none the wiser — they see a 200 and believe
552
+ # their attribution works. Worse, the opaque charset [A-Za-z0-9._:-] only
553
+ # stops values containing "@", so an SSN, a phone number, a payment card, an
554
+ # IBAN and an ABA routing number all passed it and went RAW onto the wire.
555
+ #
556
+ # Now, exactly as the TypeScript SDK does: a shape-valid, non-PII-shaped token
557
+ # is sent EXACTLY as supplied (the builder's own id — every join against their
558
+ # own systems keeps working); anything else — PII-shaped or malformed — is
559
+ # TOKENISED here, before the value touches the network.
560
+ #
561
+ # The call is NEVER refused. Only an absent/empty end_user omits the header,
562
+ # because there is nothing to attribute.
563
+ def self.end_user_header_value(raw, secret)
564
+ return nil unless raw.is_a?(String)
565
+ return nil if raw.strip.empty?
566
+ ref = sanitize_end_user(raw)
567
+ return ref if !ref.nil? && !looks_like_end_user_pii?(ref)
568
+ pseudonymise_end_user(raw, secret)
569
+ end
570
+
571
+ # Resolve the attribution app slug: explicit value else the CLOAK_APP_ID env
572
+ # var. Sanitised; nil when unset/invalid.
573
+ def self.resolve_app_id(app_id)
574
+ candidate = app_id
575
+ candidate = ENV["CLOAK_APP_ID"] if candidate.nil? || candidate == ""
576
+ sanitize_app_id(candidate)
577
+ end
578
+
579
+ # KOMITÉ-ORDRE 10 §Q45 (sak 181) — TOKENISE, NEVER REFUSE. A shape-valid
580
+ # non-PII token goes out exactly as supplied; everything else is tokenised
581
+ # HERE, before the network. The header is omitted only when there is nothing
582
+ # to attribute. See .end_user_header_value.
583
+ def end_user_header(end_user)
584
+ value = self.class.end_user_header_value(end_user, @end_user_secret || @api_key)
585
+ value.nil? ? {} : { "X-Cloak-End-User" => value }
586
+ end
587
+
588
+ def messages
589
+ @messages ||= Resources::Messages.new(self)
590
+ end
591
+
592
+ def chat
593
+ @chat ||= Resources::Chat.new(self)
594
+ end
595
+
596
+ # ── ADR-0014 verifiable-trust + platform resources ───────────────────────
597
+
598
+ # Receipts REST + offline verify surface (C10/C9). See Resources::Receipts.
599
+ def receipts
600
+ @receipts ||= Resources::Receipts.new(self)
601
+ end
602
+
603
+ # Live model catalogue (C11): GET /api/v1/models.
604
+ def models
605
+ @models ||= Resources::Models.new(self)
606
+ end
607
+
608
+ # Token counting is disabled because it would send content to the gateway.
609
+ def tokens
610
+ @tokens ||= Resources::Tokens.new(self)
611
+ end
612
+
613
+ # Capture the exact JSON bytes for user inspection. Content tokenisation is
614
+ # performed by the resource before it calls this method.
615
+ def prepare_review(path, body, token_map: session_token_map, streaming: false, headers: {},
616
+ engine_identity: nil, coverage: nil, warnings: [], unread: [])
617
+ payload = streaming ? body.merge(stream: true) : body
618
+ raw = JSON.generate(payload).b
619
+ call_map = token_map.select { |token, _original| whole_token_present?(raw, token) }
620
+ coverage ||= CloakAPI::Engine.available? ? CloakAPI::Coverage::FULL : CloakAPI::Coverage::RULES_ONLY
621
+ # The final local check runs HERE, before approval, so what it finds is
622
+ # in front of the reviewer; it never stops the request.
623
+ # Requests to other endpoints (receipt checks) carry no message text and
624
+ # are not scanned here.
625
+ if CONTENT_RELAY_PATHS.include?(path)
626
+ warnings = CloakAPI::Warnings.merge(warnings, final_egress_warnings(without_media(raw, unread), call_map))
627
+ end
628
+ prepared = PreparedRequest.new(self, path, raw, call_map, streaming, headers, engine_identity,
629
+ coverage: coverage, warnings: warnings)
630
+ @review_mutex.synchronize { @prepared_requests[prepared.object_id] = prepared }
631
+ prepared
632
+ end
633
+ private :prepare_review
634
+
635
+ # Send one reviewed request. Optional body allows callers/tests to prove
636
+ # that bytes changed after approval are rejected before any transport.
637
+ def post_reviewed(reviewed, path:, body: nil, streaming: false, extra_headers: {}, &block)
638
+ snapshot = consume_reviewed!(reviewed, path: path, body: body, streaming: streaming, headers: extra_headers)
639
+ reply = relay_reviewed(snapshot, &block)
640
+ CloakAPI::Response.wrap(reply, coverage: snapshot[:coverage], warnings: snapshot[:warnings])
641
+ end
642
+
643
+ def reviewed_token_map(reviewed)
644
+ @review_mutex.synchronize do
645
+ entry = @approved_requests[reviewed&.object_id]
646
+ unless entry && entry[:capability].equal?(reviewed)
647
+ raise CloakAPI::ReviewRequiredError, "explicit review is required before content can be restored"
648
+ end
649
+ entry[:token_map].dup
650
+ end
651
+ end
652
+ private :reviewed_token_map
653
+
654
+ # Send reviewed JSON to a plain REST endpoint without relay attestation.
655
+ # This is for non-model resources whose body still needs user approval.
656
+ def post_reviewed_api(reviewed, path:)
657
+ snapshot = consume_reviewed!(reviewed, path: path, streaming: false, headers: {})
658
+ unsafe_raw_api_post(path, snapshot[:raw])
659
+ end
660
+
661
+ def consume_reviewed!(reviewed, path:, body: nil, streaming: false, headers: {})
662
+ @review_mutex.synchronize do
663
+ entry = @approved_requests[reviewed&.object_id]
664
+ unless entry && entry[:capability].equal?(reviewed)
665
+ raise CloakAPI::ReviewRequiredError, "explicit review is required before content can be sent"
666
+ end
667
+ raise ArgumentError, "reviewed request path does not match" unless entry[:path] == path
668
+ raise ArgumentError, "reviewed request stream mode does not match" unless entry[:streaming] == streaming
669
+ normalized_headers = headers.transform_keys(&:to_s).transform_values { |value| value.to_s }
670
+ raise ArgumentError, "request headers changed after review" unless entry[:headers] == normalized_headers
671
+ if body && Digest::SHA256.hexdigest(JSON.generate(body).b) != entry[:digest]
672
+ raise ArgumentError, "request body changed after review"
673
+ end
674
+ @approved_requests.delete(reviewed.object_id)
675
+ entry
676
+ end
677
+ end
678
+ private :consume_reviewed!
679
+
680
+ def approve_prepared(prepared)
681
+ @review_mutex.synchronize do
682
+ stored = @prepared_requests.delete(prepared.object_id)
683
+ raise ArgumentError, "prepared request was not issued by this client" unless stored.equal?(prepared)
684
+ capability = ReviewedRequest.new(self)
685
+ @approved_requests[capability.object_id] = {
686
+ capability: capability, path: prepared.send(:path), raw: prepared.send(:raw),
687
+ digest: prepared.send(:digest), token_map: prepared.send(:token_map), streaming: prepared.send(:streaming),
688
+ headers: prepared.send(:headers), engine_identity: prepared.send(:engine_identity),
689
+ coverage: prepared.coverage, warnings: prepared.warnings
690
+ }
691
+ capability
692
+ end
693
+ end
694
+ private :approve_prepared
695
+
696
+ def relay_reviewed(snapshot, &block)
697
+ # The identity that was shown at review is the identity that is sent. A
698
+ # request prepared on the built-in rules states no engine identity; one
699
+ # prepared with the engine is only sent while that same engine is loaded.
700
+ # If that engine is no longer the one in use, the approved bytes are
701
+ # still sent, without any engine identity and marked rules_only.
702
+ identity = snapshot[:engine_identity] || [CloakAPI::Engine::RULESET_VERSION, ""]
703
+ coverage = snapshot[:coverage]
704
+ unless identity[1].to_s.empty?
705
+ current, = checked_engine_identity
706
+ unless current == identity
707
+ identity = [CloakAPI::Engine::RULESET_VERSION, ""]
708
+ coverage = CloakAPI::Coverage::RULES_ONLY
709
+ changed = CloakAPI::Warnings.reduced(
710
+ "engine_unloadable",
711
+ "The engine that prepared this request is no longer the engine in use, so the request " \
712
+ "states no engine identity."
713
+ )
714
+ snapshot[:warnings] = CloakAPI::Warnings.merge(snapshot[:warnings], changed).freeze
715
+ snapshot[:coverage] = coverage
716
+ CloakAPI::Warnings.emit(changed, once: false)
717
+ end
718
+ end
719
+ unless CONTENT_RELAY_PATHS.include?(snapshot[:path])
720
+ # A relay to another path was not scanned at prepare; scan it now.
721
+ found = final_egress_warnings(snapshot[:raw], snapshot[:token_map])
722
+ snapshot[:warnings] = CloakAPI::Warnings.merge(snapshot[:warnings], found).freeze
723
+ end
724
+ note_final_egress!(snapshot)
725
+ mac = fetch_pretokenised_mac(snapshot[:raw])
726
+ headers = relay_headers(mac, snapshot[:headers], identity, coverage)
727
+ if snapshot[:streaming]
728
+ unsafe_raw_stream(snapshot[:path], snapshot[:raw], headers, &block)
729
+ else
730
+ unsafe_raw_send(snapshot[:path], snapshot[:raw], headers)
731
+ end
732
+ end
733
+ private :relay_reviewed
734
+
735
+ # The relay headers. Engine identity (version and hash) is stated only when
736
+ # the engine ran for this request; a request prepared on the built-in rules
737
+ # carries neither.
738
+ def relay_headers(mac, extra_headers, identity, coverage = nil)
739
+ headers = {}
740
+ extra_headers.each { |k, v| headers[k] = v unless v.nil? }
741
+ headers["X-Cloak-Pretokenised"] = "1"
742
+ headers["X-Cloak-Client-MAC"] = mac
743
+ headers["X-CloakAPI-Tokenized"] = coverage.to_s.empty? ? "true" : "true;coverage=#{coverage}"
744
+ version, hash = identity
745
+ if hash.to_s.empty?
746
+ # Same wire as the TypeScript engineIdentityHeaders: with no binary hash,
747
+ # X-Cloak-Engine-Hash-Status is "unavailable" and version and hash are omitted.
748
+ # The status is not an engine identity.
749
+ headers["X-Cloak-Engine-Hash-Status"] = "unavailable"
750
+ else
751
+ headers["X-Cloak-Engine-Version"] = version
752
+ headers["X-Cloak-Engine-Hash"] = hash
753
+ end
754
+ headers
755
+ end
756
+ private :relay_headers
757
+
758
+ # The engine identity for a relay: +[version, hash]+, with +hash+ "" when no
759
+ # engine is used. It never refuses because of the engine: a missing, wrong
760
+ # or unloadable engine or pin means the built-in rules, with a notice. Only
761
+ # the explicit strict option (strict_coverage: true) raises here.
762
+ def validate_engine_identity!(allow_rules_only: true)
763
+ identity, warning = checked_engine_identity
764
+ if warning
765
+ CloakAPI::Degraded.guard!("relay text", @allow_reduced_coverage, CloakAPI::Degraded::KIND_NO_ENGINE)
766
+ CloakAPI::Warnings.emit(warning)
767
+ end
768
+ identity
769
+ end
770
+
771
+ # +[identity, warning]+. The engine loader has already applied the pin
772
+ # rule; this second look, at the moment of use, states an engine identity
773
+ # only when it is a well-formed SHA-256 for this SDK's rule set that is
774
+ # either the pinned value or a build this release names. Anything else is
775
+ # the built-in-rules identity (no hash) plus the notice that says why.
776
+ def checked_engine_identity
777
+ rules = [CloakAPI::Engine::RULESET_VERSION, ""]
778
+ version, hash = CloakAPI::Engine.identity
779
+ hash = hash.to_s
780
+ if hash.empty?
781
+ status = CloakAPI::Engine.status
782
+ warning = status.warning || CloakAPI::Warnings.reduced(
783
+ "engine_missing", "The CloakAPI on-device engine is not in use. #{CloakAPI::Engine::RULES_NOTE}"
784
+ )
785
+ return [rules, warning]
786
+ end
787
+ unless version == CloakAPI::Engine::RULESET_VERSION && hash.match?(/\A[0-9a-fA-F]{64}\z/)
788
+ return [rules, CloakAPI::Warnings.reduced(
789
+ "ruleset_mismatch",
790
+ "The loaded engine does not report the rule set this SDK expects, so it was not used. " \
791
+ "#{CloakAPI::Engine::RULES_NOTE}"
792
+ )]
793
+ end
794
+ pin = ENV[CloakAPI::Engine::ENV_PIN].to_s
795
+ if pin.empty?
796
+ unless CloakAPI::Engine::RELEASE_SET_NATIVE.value?(hash.downcase)
797
+ return [rules, CloakAPI::Warnings.reduced(
798
+ "pin_missing",
799
+ "#{CloakAPI::Engine::ENV_PIN} is not set, so the loaded engine was not used. #{CloakAPI::Engine::RULES_NOTE}"
800
+ )]
801
+ end
802
+ elsif !(pin.match?(/\A[0-9a-fA-F]{64}\z/) && pin.casecmp?(hash))
803
+ return [rules, CloakAPI::Warnings.reduced(
804
+ "pin_mismatch",
805
+ "#{CloakAPI::Engine::ENV_PIN} does not match the SHA-256 of the loaded engine, so that engine was not used. " \
806
+ "#{CloakAPI::Engine::RULES_NOTE}"
807
+ )]
808
+ end
809
+ [[version, hash], nil]
810
+ end
811
+ private :checked_engine_identity
812
+
813
+ # What the final local check finds in the exact outgoing bytes: text in a
814
+ # script this device cannot check, or a value that still looks like
815
+ # personal data outside the replaced strings (an object key, a number).
816
+ # Reported, never refused.
817
+ # The outgoing bytes without the media values that were passed through
818
+ # unread: the final check is about text, and base64 is not text.
819
+ def without_media(raw, unread)
820
+ return raw if unread.empty?
821
+
822
+ text = raw.dup.force_encoding(Encoding::UTF_8)
823
+ strings = []
824
+ collect = lambda do |value|
825
+ case value
826
+ when String then strings << value unless value.empty?
827
+ when Hash then value.each_value(&collect)
828
+ when Array then value.each(&collect)
829
+ end
830
+ end
831
+ unread.each(&collect)
832
+ strings.uniq.sort_by { |string| -string.length }.each do |string|
833
+ text = text.gsub(JSON.generate(string)[1..-2]) { "" }
834
+ end
835
+ text
836
+ rescue EncodingError, ArgumentError
837
+ raw
838
+ end
839
+ private :without_media
840
+
841
+ def final_egress_warnings(raw, token_map)
842
+ text = raw.dup.force_encoding(Encoding::UTF_8)
843
+ masked = text.dup
844
+ token_map.keys.sort_by { |token| -token.length }.each do |token|
845
+ masked.gsub!(token, "\u0000")
846
+ end
847
+ found = []
848
+ if masked.match?(/[\u0E00-\u0E7F\u1780-\u17FF]/)
849
+ found << CloakAPI::Warnings.unchecked("unverified_script", CloakAPI::Warnings::UNVERIFIED_SCRIPT_MESSAGE)
850
+ end
851
+ unless CloakAPI::Pii::Detector.new.detect(masked).empty?
852
+ found << CloakAPI::Warnings.unchecked("value_not_replaced", CloakAPI::Warnings::VALUE_NOT_REPLACED_MESSAGE)
853
+ end
854
+ found
855
+ rescue EncodingError, ArgumentError
856
+ [CloakAPI::Warnings.unchecked("value_not_replaced", CloakAPI::Warnings::VALUE_NOT_REPLACED_MESSAGE)]
857
+ end
858
+ private :final_egress_warnings
859
+
860
+ # Kept for callers of the pre-1.4.0 name: runs the final local check on a
861
+ # reviewed snapshot, records and prints what it found, and returns true.
862
+ def validate_final_egress!(snapshot)
863
+ unless snapshot.key?(:warnings)
864
+ snapshot = snapshot.merge(warnings: final_egress_warnings(snapshot[:raw], snapshot[:token_map]))
865
+ end
866
+ note_final_egress!(snapshot)
867
+ true
868
+ end
869
+
870
+ # Once per send: one line on the error stream for content that could not be
871
+ # checked, and the same state on last_detection_status.
872
+ def note_final_egress!(snapshot)
873
+ unchecked = snapshot[:warnings].to_a.select { |warning| warning.code == CloakAPI::Warnings::UNCHECKED }
874
+ return if unchecked.empty?
875
+
876
+ warning = "CloakAPI: the final local check could not verify all outbound text. The reviewed request will still be sent."
877
+ @token_mutex.synchronize do
878
+ status = (@last_detection_status || {}).dup
879
+ status[:coverage] = "unverified"
880
+ status[:degraded] = true
881
+ status[:warning] = [status[:warning], warning].compact.reject(&:empty?).join("; ")
882
+ @last_detection_status = status
883
+ end
884
+ unchecked.each { |notice| CloakAPI::Warnings.emit(notice, once: false) }
885
+ end
886
+ private :note_final_egress!
887
+
888
+ # On-device detokenise -> target file format (C13), fully local.
889
+ def reconstruct
890
+ @reconstruct ||= Resources::Reconstruct.new(self)
891
+ end
892
+
893
+ # Client-side arbitrage router + versioned catalogue (C19). Lazily built from
894
+ # the options passed at construction. Returns a CloakAPI::Routing::Router.
895
+ def router
896
+ @router ||= CloakAPI::Routing::Router.new(**@routing_options)
897
+ end
898
+
899
+ # Privacy posture (C20): honest, content-free descriptor of what this
900
+ # integration protects (engine identity + fail-closed + tiers + detectors).
901
+ def privacy_posture(**opts)
902
+ version, hash = CloakAPI::Engine.identity
903
+ CloakAPI::Posture.privacy_posture({ version: version, hash: hash }, **opts)
904
+ end
905
+
906
+ # Relay a CLIENT-TOKENISED body under the Level-1-only STRICT gateway. The
907
+ # body is marshalled ONCE (the exact bytes that egress), the per-body
908
+ # pre-tokenised MAC is minted over those bytes (FAIL-LOUD — never relays
909
+ # without it), and those SAME bytes are sent with the proof + engine-identity
910
+ # headers the fail-closed gateway requires. Mirrors Go's doRelayRequest.
911
+ #
912
+ # @param path [String] gateway path, e.g. "/api/v1/messages"
913
+ # @param body [Hash] JSON-serialisable request body (already tokenised)
914
+ # @return [Hash] decoded JSON response
915
+ # @raise [PretokenisedMacError] when the MAC could not be obtained (no relay)
916
+ # @raise [ApiError] on 4xx/5xx after max retries
917
+ def unsafe_raw_post(path, body, extra_headers = {})
918
+ identity = validate_engine_identity!(allow_rules_only: true)
919
+ # The EXACT bytes that will egress — the MAC must cover THESE bytes, and
920
+ # send_raw sends them verbatim, so the gateway's constant-time check passes.
921
+ raw = JSON.generate(body)
922
+ mac = fetch_pretokenised_mac(raw) # fail-loud: never relay without the proof
923
+
924
+ headers = relay_headers(mac, extra_headers, identity, raw_relay_coverage(identity))
925
+
926
+ unsafe_raw_send(path, raw, headers)
927
+ end
928
+
929
+ # Streaming relay (C15): identical proof/identity envelope to #post, but opens
930
+ # an SSE stream instead of a single JSON response. The body is marshalled ONCE
931
+ # (the exact egress bytes), the per-body MAC is minted over those bytes
932
+ # (fail-loud), and each parsed SSE event Hash is yielded to the block. Reply
933
+ # detokenisation across chunk boundaries is the caller's (resource's) job via
934
+ # {CloakAPI::Streaming::Detokenizer}. Mirrors the Go/Python SSE relay.
935
+ def unsafe_raw_post_stream(path, body, extra_headers = {}, &block)
936
+ identity = validate_engine_identity!(allow_rules_only: true)
937
+ raw = JSON.generate(body.merge(stream: true))
938
+ mac = fetch_pretokenised_mac(raw)
939
+
940
+ headers = relay_headers(mac, extra_headers, identity, raw_relay_coverage(identity))
941
+
942
+ unsafe_raw_stream(path, raw, headers, &block)
943
+ end
944
+
945
+ # The unsafe_raw_* calls take a body the caller tokenised. Without an
946
+ # engine the only coverage that can have produced it is the built-in rules;
947
+ # with one, the SDK does not know and states none.
948
+ def raw_relay_coverage(identity)
949
+ identity[1].to_s.empty? ? CloakAPI::Coverage::RULES_ONLY : nil
950
+ end
951
+ private :raw_relay_coverage
952
+
953
+ # Mint the per-body passthrough MAC for +raw_body+ (the EXACT bytes that will
954
+ # be relayed) via POST /api/v1/pretokenised/mac on the tenant's own API key —
955
+ # so the client never holds the raw tenant HMAC key. The gateway returns
956
+ # {"mac": ...} (or {"data": {"mac": ...}}), the HMAC-SHA256 of those bytes.
957
+ #
958
+ # FAIL-LOUD: any failure (transport error, non-2xx, or a missing +mac+) raises
959
+ # PretokenisedMacError so the relay is NEVER sent without the proof. There is
960
+ # deliberately no no-MAC fallback — under Level-1-only that would just be 4xx'd.
961
+ def fetch_pretokenised_mac(raw_body)
962
+ out = unsafe_raw_send(PRETOKENISED_MAC_PATH, raw_body, {})
963
+ mac = out["mac"]
964
+ mac = out.dig("data", "mac") if mac.nil? || mac == ""
965
+ unless mac.is_a?(String) && mac.match?(/\A[0-9a-f]{64}\z/)
966
+ raise PretokenisedMacError.new("the pre-tokenised MAC endpoint returned no usable 'mac' field")
967
+ end
968
+
969
+ mac
970
+ rescue PretokenisedMacError
971
+ raise
972
+ rescue ApiError => e
973
+ raise PretokenisedMacError.new(e), cause: nil
974
+ rescue StandardError => e
975
+ raise PretokenisedMacError.new(e), cause: nil
976
+ end
977
+
978
+ # Low-level wire send: POST pre-marshalled +raw+ body bytes VERBATIM and
979
+ # decode the JSON response. POSTs are one-shot: replay after a retryable
980
+ # response can duplicate a relay or a pre-tokenised-MAC request. The relay
981
+ # path (#post) mints its MAC over these EXACT bytes then hands them here
982
+ # unchanged, so the bytes the MAC covers are byte-identical to those that
983
+ # egress. Mirrors Go's sendRaw.
984
+ #
985
+ # @raise [ApiError] on a non-2xx response
986
+ def unsafe_raw_send(path, raw, extra_headers = {})
987
+ transport("POST", path, raw, extra_headers, retry_request: false)
988
+ end
989
+
990
+ # Plain authenticated GET returning decoded JSON. Used by the pure-HTTP
991
+ # resources (models C11, receipts REST C10) — NOT a relay, so it carries no
992
+ # pretokenised MAC / engine-identity headers.
993
+ def unsafe_raw_api_get(path, extra_headers = {})
994
+ transport("GET", path, nil, extra_headers)
995
+ end
996
+
997
+ # Plain authenticated POST of a JSON +body+, returning decoded JSON. Used by
998
+ # the pure-HTTP resources that are NOT content relays (tokens.count C12,
999
+ # receipts verify/countersign C10) — so, deliberately, no MAC + no engine
1000
+ # headers (the relay path is #post).
1001
+ # Explicitly named raw API POST for callers that knowingly bypass local
1002
+ # review. Content-bearing public resources use prepare -> approve instead.
1003
+ def unsafe_raw_api_post(path, raw, extra_headers = {})
1004
+ transport("POST", path, raw, extra_headers, retry_request: false)
1005
+ end
1006
+
1007
+ # One wire-level transport for every verb. Mirrors send_raw's retry/backoff.
1008
+ #
1009
+ # @raise [ApiError] on 4xx/5xx after max retries
1010
+ def transport(method, path, raw, extra_headers = {}, retry_request: true)
1011
+ uri = checked_uri(path)
1012
+ last_error = nil
1013
+ attempts = retry_request ? max_retries + 1 : 1
1014
+
1015
+ attempts.times do |attempt|
1016
+ sleep([(2 ** (attempt - 1)), 30].min) if attempt > 0
1017
+
1018
+ req = build_request(method, uri, extra_headers)
1019
+ req.body = raw unless raw.nil?
1020
+
1021
+ begin
1022
+ resp = @http_request.call(req)
1023
+ status = resp.code.to_i
1024
+ rbody = resp.body
1025
+
1026
+ if (200...300).include?(status)
1027
+ begin
1028
+ return JSON.parse(rbody)
1029
+ rescue JSON::ParserError, TypeError
1030
+ # A 2xx already left the machine. Retrying it would send the same
1031
+ # body again. The body itself stays out of the error.
1032
+ raise ApiError.new("response decode failed", status, "", "")
1033
+ end
1034
+ end
1035
+
1036
+ err = parse_api_error(status, rbody, resp['Retry-After'])
1037
+ if retry_request && retryable?(status) && attempt < max_retries
1038
+ last_error = err
1039
+ next
1040
+ end
1041
+ raise err
1042
+ rescue ApiError
1043
+ raise
1044
+ rescue => e
1045
+ last_error = ApiError.new("Request failed", 0, "", "")
1046
+ end
1047
+ end
1048
+
1049
+ raise last_error || ApiError.new("Max retries exceeded", 0, "", "")
1050
+ end
1051
+
1052
+ # Open an SSE stream: POST +raw+ and yield each parsed SSE event Hash (or
1053
+ # +nil+ at [DONE]) to the block as it arrives. Boundary-safe — SSE frames are
1054
+ # split on blank lines across chunk boundaries. No retry (a stream can't be
1055
+ # transparently replayed mid-flight). Mirrors the Python streaming parser.
1056
+ #
1057
+ # @yieldparam event [Hash, nil] the decoded `data:` JSON of one SSE frame
1058
+ def unsafe_raw_stream(path, raw, extra_headers = {})
1059
+ uri = checked_uri(path)
1060
+
1061
+ req = build_request("POST", uri, extra_headers.merge("Accept" => "text/event-stream"))
1062
+ req.body = raw
1063
+
1064
+ @http_request.call(req) do |resp|
1065
+ status = resp.code.to_i
1066
+ unless (200...300).include?(status)
1067
+ raise parse_api_error(status, resp.body.to_s, resp['Retry-After'])
1068
+ end
1069
+
1070
+ buffer = +""
1071
+ terminated = false
1072
+ resp.read_body do |chunk|
1073
+ buffer << chunk
1074
+ while (match = /(?:\r\n|\r|\n)(?:\r\n|\r|\n)/.match(buffer))
1075
+ frame = buffer.slice!(0, match.end(0))
1076
+ yield_sse_frame(frame) do |ev, event_name|
1077
+ terminated = true if stream_terminator?(ev, event_name)
1078
+ raise sanitized_stream_error(ev) if error_event?(ev, event_name)
1079
+ yield ev
1080
+ end
1081
+ end
1082
+ end
1083
+ unless buffer.strip.empty?
1084
+ yield_sse_frame(buffer) do |ev, event_name|
1085
+ terminated = true if stream_terminator?(ev, event_name)
1086
+ raise sanitized_stream_error(ev) if error_event?(ev, event_name)
1087
+ yield ev
1088
+ end
1089
+ end
1090
+ unless terminated
1091
+ raise ApiError.new("Gateway returned an error during the stream", 502, "stream_truncated", "api_error")
1092
+ end
1093
+ end
1094
+ end
1095
+
1096
+ private
1097
+
1098
+ private :transport, :fetch_pretokenised_mac
1099
+
1100
+ def checked_uri(path)
1101
+ value = path.to_s
1102
+ unless value.start_with?("/") && !value.start_with?("//") && !value.include?("@") && !value.match?(/[\r\n]/)
1103
+ raise ArgumentError, "request path must be an absolute same-origin path"
1104
+ end
1105
+ base = URI.parse(base_url)
1106
+ uri = URI.join(base_url + "/", value.delete_prefix("/"))
1107
+ unless uri.scheme == base.scheme && uri.host == base.host && uri.port == base.port && uri.userinfo.nil?
1108
+ raise ArgumentError, "request path must remain on the configured origin"
1109
+ end
1110
+ uri
1111
+ rescue URI::InvalidURIError
1112
+ raise ArgumentError, "request path must be a valid same-origin path"
1113
+ end
1114
+
1115
+ # Is +token+ (a stand-in) in the outgoing bytes as a value of its own, and
1116
+ # not merely as part of a longer word ("Hall" inside "Hallway", "olsen"
1117
+ # inside "kristin.olsen@example.no")? Only such stand-ins travel with the
1118
+ # request, and only they are restored in its reply.
1119
+ #
1120
+ # A letter, digit or underscore directly before or after makes it part of a
1121
+ # longer word. So does one of @ . + - when a letter or digit follows on
1122
+ # its far side ("olsen.no", "a@b"). The same characters as plain
1123
+ # punctuation do not: until 1.4.0 a stand-in at the end of a sentence
1124
+ # ("... on +47 614 94 308.") was taken for part of a word, left out of the
1125
+ # request's map and came back unrestored in the reply.
1126
+ def whole_token_present?(raw, token)
1127
+ text = raw.dup.force_encoding(Encoding::UTF_8)
1128
+ # A bracketed marker cannot be part of a word.
1129
+ return text.include?(token) if token.start_with?("<<CLOAK:", "[CLK-")
1130
+
1131
+ start = 0
1132
+ while (index = text.index(token, start))
1133
+ after_index = index + token.length
1134
+ before_word = joins_word?(index.positive? ? text[index - 1] : nil, index > 1 ? text[index - 2] : nil)
1135
+ after_word = joins_word?(text[after_index], text[after_index + 1])
1136
+ return true unless before_word || after_word
1137
+
1138
+ start = index + 1
1139
+ end
1140
+ false
1141
+ end
1142
+
1143
+ def joins_word?(neighbour, beyond)
1144
+ return false if neighbour.nil?
1145
+ return true if neighbour.match?(/[\p{Alnum}_]/u)
1146
+
1147
+ neighbour.match?(/[@.+-]/) && !beyond.nil? && beyond.match?(/[\p{Alnum}_]/u)
1148
+ end
1149
+ private :joins_word?
1150
+ private :whole_token_present?
1151
+
1152
+ def stream_terminator?(event, event_name)
1153
+ return true if event.nil?
1154
+ return false unless event.is_a?(Hash)
1155
+ return true if event_name.to_s == "message_stop" || event["type"].to_s == "message_stop"
1156
+
1157
+ # OpenAI completes a stream with a non-null finish_reason on any choice.
1158
+ # JSON null is not a completion; data: [DONE] is not required after that.
1159
+ choices = event["choices"]
1160
+ return false unless choices.is_a?(Array)
1161
+
1162
+ choices.any? do |choice|
1163
+ choice.is_a?(Hash) && choice.key?("finish_reason") && !choice["finish_reason"].nil?
1164
+ end
1165
+ end
1166
+
1167
+ # `event: error` and `type: "error"` are error frames even when the JSON
1168
+ # value is null. The null check applies only to other frames, so a content
1169
+ # frame that carries `"error": null` next to `choices` keeps its text.
1170
+ def error_event?(event, event_name = nil)
1171
+ return false if event.nil?
1172
+ return true if event_name.to_s == "error"
1173
+ return false unless event.is_a?(Hash)
1174
+ return true if event["type"].to_s == "error"
1175
+ return false unless event.key?("error")
1176
+
1177
+ !event["error"].nil?
1178
+ end
1179
+
1180
+ def sanitized_stream_error(event)
1181
+ nested = event.is_a?(Hash) && event["error"].is_a?(Hash) ? event["error"] : nil
1182
+ # A flat {"code":"..."} on event: error is still a quota frame. Anything
1183
+ # else, including "error": null, keeps the fixed gateway code.
1184
+ source = nested || (event.is_a?(Hash) ? event : {})
1185
+ code = source["code"]
1186
+ quota = %w[hourly_quota_exceeded daily_quota_exceeded quota_counter_corrupt quota_counter_unavailable].include?(code)
1187
+ ApiError.new("Gateway returned an error during the stream", quota ? 429 : 502,
1188
+ quota ? code : "gateway_error", quota ? "rate_limit_error" : "api_error")
1189
+ end
1190
+
1191
+ # Build one Net::HTTP request with the standard CloakAPI headers.
1192
+ def build_request(method, uri, extra_headers)
1193
+ klass = method.to_s.upcase == "GET" ? Net::HTTP::Get : Net::HTTP::Post
1194
+ req = klass.new(uri.request_uri)
1195
+ req["Authorization"] = "Bearer #{api_key}"
1196
+ req["Content-Type"] = "application/json"
1197
+ req["Accept"] = "application/json"
1198
+ req["User-Agent"] = "cloakapi-ruby/#{SDK_VERSION}"
1199
+ req["X-CloakAPI-SDK"] = "ruby/#{SDK_VERSION}"
1200
+ # ADR-0015 — attribution app slug on every call (optional; content-free).
1201
+ req["X-Cloak-App-Id"] = @app_id unless @app_id.nil?
1202
+ # ── SAK 452 (2026-08-10) — MODUSEN GJEKK ALDRI PÅ WIRE ────────────────
1203
+ # Målt: 0 treff på "Privacy-Tier" i heile `lib/`. `SurrogateMode.resolve`
1204
+ # blei kalla i #initialize (linje 106), verdien blei lagra i
1205
+ # @surrogate_mode, brukt lokalt — og aldri sendt. Ein Ruby-kunde som
1206
+ # konstruerte klienten med surrogate_mode: "max" fekk gatewayen sin
1207
+ # standard, med 200 og ingen feilmelding. Sjette forma på wire-nivå.
1208
+ #
1209
+ # Han står HER, i den EINE staden alle Ruby-førespurnader blir bygde, og
1210
+ # FØR extra_headers-loopen — so eit kall som set headeren eksplisitt
1211
+ # framleis overstyrer klient-standarden.
1212
+ #
1213
+ # Kanonisk namn. Gatewayen les òg aliaset `X-CloakAPI-Tier`
1214
+ # (PrivacyTierResolver.php:75), men vi sender det kanoniske (sak 454).
1215
+ req[HEADER_PRIVACY_TIER] = @surrogate_mode unless @surrogate_mode.nil?
1216
+ extra_headers.each { |k, v| req[k] = v unless v.nil? }
1217
+ req
1218
+ end
1219
+
1220
+ # Parse one raw SSE frame (a run of lines ended by a blank line) into its
1221
+ # decoded `data:` JSON and yield it. Yields nothing on a comment/empty frame;
1222
+ # yields +nil+ on a `data: [DONE]` sentinel so the caller can stop.
1223
+ def yield_sse_frame(frame)
1224
+ event_name = "message"
1225
+ data_parts = []
1226
+ frame.split(/\r\n|\r|\n/).each do |line|
1227
+ line = line.chomp
1228
+ if line.start_with?("event:")
1229
+ event_name = line[6..].strip
1230
+ next
1231
+ end
1232
+ next unless line.start_with?("data:")
1233
+
1234
+ payload = line[5..].strip
1235
+ return yield(nil, event_name) if payload == "[DONE]"
1236
+
1237
+ data_parts << payload
1238
+ end
1239
+ return if data_parts.empty?
1240
+
1241
+ begin
1242
+ yield JSON.parse(data_parts.join(" ")), event_name
1243
+ rescue JSON::ParserError
1244
+ raise ApiError.new("Gateway returned an error during the stream", 502, "stream_error", "api_error"), cause: nil
1245
+ end
1246
+ end
1247
+
1248
+ def retryable?(code)
1249
+ [429, 502, 503, 504].include?(code)
1250
+ end
1251
+
1252
+ def parse_api_error(status, body, retry_after_header = nil)
1253
+ parsed = JSON.parse(body) rescue {}
1254
+ err = parsed["error"] || {}
1255
+ code = err["code"] || ""
1256
+ ApiError.new("CloakAPI request failed", status, code, err["type"] || "", parse_retry_after(retry_after_header))
1257
+ rescue
1258
+ ApiError.new("CloakAPI request failed", status, "", "")
1259
+ end
1260
+
1261
+ def parse_retry_after(value)
1262
+ return nil unless value.is_a?(String) && !value.strip.empty?
1263
+ seconds = Float(value, exception: false)
1264
+ if seconds && seconds.finite? && seconds >= 0
1265
+ return [seconds, 3600].min
1266
+ end
1267
+ at = Time.httpdate(value) rescue nil
1268
+ return nil unless at
1269
+ [[at - Time.now, 0].max, 3600].min
1270
+ end
1271
+ end
1272
+ end