cloakapi 1.4.1
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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +160 -0
- data/LICENSE +202 -0
- data/NOTICE +18 -0
- data/README.md +407 -0
- data/THIRD-PARTY-NOTICES.md +22 -0
- data/TRADEMARKS.md +19 -0
- data/examples/fake_gateway.rb +78 -0
- data/examples/hello.rb +64 -0
- data/lib/cloakapi/client.rb +1272 -0
- data/lib/cloakapi/degraded.rb +77 -0
- data/lib/cloakapi/disclosure.rb +252 -0
- data/lib/cloakapi/engine.rb +702 -0
- data/lib/cloakapi/errors.rb +65 -0
- data/lib/cloakapi/pii/bundled_rules.rb +670 -0
- data/lib/cloakapi/pii/card_spans.rb +300 -0
- data/lib/cloakapi/pii/detector.rb +1925 -0
- data/lib/cloakapi/pii/patterns.json +2238 -0
- data/lib/cloakapi/pii/pii_match.rb +7 -0
- data/lib/cloakapi/pii/pii_type.rb +7 -0
- data/lib/cloakapi/pii/ruleset.rb +65 -0
- data/lib/cloakapi/pii/tokenizer.rb +411 -0
- data/lib/cloakapi/posture.rb +82 -0
- data/lib/cloakapi/receipts.rb +406 -0
- data/lib/cloakapi/resources/chat.rb +82 -0
- data/lib/cloakapi/resources/messages.rb +90 -0
- data/lib/cloakapi/resources/models.rb +25 -0
- data/lib/cloakapi/resources/receipts.rb +162 -0
- data/lib/cloakapi/resources/reconstruct.rb +120 -0
- data/lib/cloakapi/resources/request_strings.rb +485 -0
- data/lib/cloakapi/resources/reviewable.rb +163 -0
- data/lib/cloakapi/resources/tokens.rb +28 -0
- data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
- data/lib/cloakapi/routing.rb +500 -0
- data/lib/cloakapi/streaming.rb +196 -0
- data/lib/cloakapi/surrogate_mode.rb +233 -0
- data/lib/cloakapi/version.rb +15 -0
- data/lib/cloakapi/warnings.rb +137 -0
- data/lib/cloakapi.rb +37 -0
- data/licenses/Apache-2.0.txt +202 -0
- data/licenses/CC-BY-4.0.txt +104 -0
- data/licenses/MIT-Faker.txt +21 -0
- data/licenses/MIT.txt +21 -0
- metadata +149 -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
|