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,196 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloakAPI
4
+ # SSE streaming + BOUNDARY-SAFE cross-stream detokenise (C15).
5
+ #
6
+ # The gateway relays the upstream provider's SSE stream verbatim; the SDK
7
+ # detokenises reply chunks ON-DEVICE as they arrive. A replacement can be SPLIT
8
+ # across two SSE deltas, so a naive per-chunk +gsub+ sees neither half and the
9
+ # stand-in reaches the reader VERBATIM:
10
+ #
11
+ # chunk 1: "...mail emily.rivera@w"
12
+ # chunk 2: "estmarch.co.uk, ok?"
13
+ #
14
+ # Under MAX that leak is at least VISIBLE (a stray +<<CLOAK:...>>+ marker looks
15
+ # obviously wrong). Under BALANCED — the DEFAULT — the stand-in is a plausible
16
+ # value, so the corruption is SILENT: the user reads a stranger's address as
17
+ # though it were their own. {Detokenizer} withholds any trailing text that could
18
+ # still grow into a replacement and releases it once the replacement completes
19
+ # (or at {Detokenizer#flush}, which callers MUST call at end-of-stream).
20
+ #
21
+ # Mirrors the Python +StreamDetokenizer+ (cloakapi/pii/tokenizer.py), the PHP
22
+ # +StreamDetokeniser+ and the Rust +BoundaryDetokenizer+.
23
+ module Streaming
24
+ # Boundary-safe incremental detokeniser. Feed it reply text deltas; it returns
25
+ # the safe-to-emit, detokenised prefix and holds back any tail that could
26
+ # still turn out to be part of a replacement.
27
+ #
28
+ # The hold-back rule is MODE-INDEPENDENT and has TWO parts, both required:
29
+ #
30
+ # 1. withhold the LONGEST suffix of the buffer that is a PROPER PREFIX of
31
+ # some key — it might still grow into a full key;
32
+ # 2. then pull that boundary BACK out of any COMPLETE key occurrence it
33
+ # would otherwise cut in half.
34
+ #
35
+ # Part 2 is not hypothetical. With the buffer ending +"...addr 2754 Laurel
36
+ # Drive"+, the trailing +"e"+ is a valid prefix of the key
37
+ # +"emily.rivera@..."+, so part 1 alone withholds one character — slicing the
38
+ # ALREADY-COMPLETE key into +"2754 Laurel Driv"+ plus a held +"e"+, after
39
+ # which NEITHER piece matches and the stand-in is emitted verbatim. Part 1
40
+ # alone therefore reintroduces, one character further along, the very defect
41
+ # this class exists to fix.
42
+ #
43
+ # Emission is delayed by at most <tt>max(key length) - 1</tt> characters, and
44
+ # the hold-back is computed against the ACTUAL key set (not a fixed window),
45
+ # so a table of short keys delays nothing measurable.
46
+ class Detokenizer
47
+ # @param token_map [Hash] replacement-string => original (the session map)
48
+ def initialize(token_map)
49
+ @token_map = token_map || {}
50
+ @max_key = @token_map.keys.map { |k| k.to_s.length }.max || 0
51
+ @pending = +""
52
+ end
53
+
54
+ # Push the next raw text delta; return the detokenised text that is safe to
55
+ # emit now (may be "" while a partial replacement is still buffered).
56
+ def push(text)
57
+ return "" if text.nil? || text.empty?
58
+ return text if @token_map.empty?
59
+
60
+ @pending << text
61
+ b = boundary(@pending)
62
+ emit = @pending[0, b]
63
+ @pending = @pending[b..].dup
64
+ detokenise(emit)
65
+ end
66
+
67
+ # Release the withheld tail at end-of-stream (detokenised). ALWAYS call
68
+ # this — whatever is held back when the stream ends is otherwise DROPPED,
69
+ # which truncates the reply.
70
+ def flush
71
+ out = detokenise(@pending)
72
+ @pending = +""
73
+ out
74
+ end
75
+
76
+ private
77
+
78
+ # Length of the suffix of +s+ that is a PROPER PREFIX of some key. That
79
+ # suffix might still become a full key once more of the stream arrives, so
80
+ # it must not be emitted yet; anything before it is final.
81
+ def holdback(s)
82
+ return 0 if @token_map.empty?
83
+
84
+ limit = [s.length, @max_key - 1].min
85
+ limit.downto(1) do |n|
86
+ tail = s[s.length - n, n]
87
+ @token_map.each_key do |key|
88
+ k = key.to_s
89
+ return n if k.length > n && k.start_with?(tail)
90
+ end
91
+ end
92
+ 0
93
+ end
94
+
95
+ # Index up to which +s+ is final and can be detokenised + emitted. Starts
96
+ # from the possible-prefix hold-back, then pulls the boundary BACK out of
97
+ # any COMPLETE key occurrence it would cut in half (see the class docs).
98
+ def boundary(s)
99
+ b = s.length - holdback(s)
100
+ moved = true
101
+ while moved && b.positive?
102
+ moved = false
103
+ @token_map.each_key do |key|
104
+ k = key.to_s
105
+ next if k.empty?
106
+
107
+ start = 0
108
+ loop do
109
+ i = s.index(k, start)
110
+ break if i.nil? || i >= b
111
+
112
+ if i < b && b < i + k.length
113
+ b = i
114
+ moved = true
115
+ break
116
+ end
117
+ start = i + 1
118
+ end
119
+ end
120
+ end
121
+ b
122
+ end
123
+
124
+ # Whole-string detokenise, LONGEST KEY FIRST so a replacement that is a
125
+ # substring of another (a surname inside a full name) cannot corrupt the
126
+ # longer one. Delegates to the SDK's one canonical detokenise.
127
+ def detokenise(text)
128
+ return text if text.nil? || text.empty? || @token_map.empty?
129
+
130
+ CloakAPI::Pii.detokenize(text, @token_map)
131
+ end
132
+ end
133
+
134
+ # Detokenise the text-bearing fields of one parsed SSE event Hash IN PLACE
135
+ # using +detok+ (a {Detokenizer}). Handles both the Anthropic
136
+ # (+content_block_delta+ → +delta.text+) and OpenAI
137
+ # (+choices[].delta.content+) stream shapes. Returns the same Hash.
138
+ def self.detokenise_event(event, detok)
139
+ return event unless event.is_a?(Hash)
140
+
141
+ # Anthropic: {"type":"content_block_delta","delta":{"type":"text_delta","text":...}}
142
+ delta = event["delta"]
143
+ if delta.is_a?(Hash) && delta["text"].is_a?(String)
144
+ delta["text"] = detok.push(delta["text"])
145
+ end
146
+
147
+ # OpenAI: {"choices":[{"delta":{"content":...}}]}
148
+ choices = event["choices"]
149
+ if choices.is_a?(Array)
150
+ choices.each do |choice|
151
+ next unless choice.is_a?(Hash)
152
+
153
+ cd = choice["delta"]
154
+ cd["content"] = detok.push(cd["content"]) if cd.is_a?(Hash) && cd["content"].is_a?(String)
155
+ end
156
+ end
157
+ event
158
+ end
159
+
160
+ # End-of-stream tail release. {Detokenizer#push} withholds any trailing text
161
+ # that could still complete a replacement, so at end-of-stream something is
162
+ # usually still buffered. If nobody calls this, that tail is silently DROPPED
163
+ # and the reply is truncated mid-value.
164
+ #
165
+ # Returns a synthetic terminal event in the SAME shape the stream was using —
166
+ # so a consumer's existing text extraction picks the tail up with no special
167
+ # casing — or +nil+ when nothing was held back. The event carries
168
+ # +"cloak_flush" => true+ so a caller that wants to tell it apart from a real
169
+ # upstream frame can.
170
+ #
171
+ # @param detok [Detokenizer]
172
+ # @param shape [Symbol] +:anthropic+ or +:openai+
173
+ def self.flush_event(detok, shape)
174
+ tail = detok.flush
175
+ return nil if tail.nil? || tail.empty?
176
+
177
+ case shape
178
+ when :anthropic
179
+ {
180
+ "type" => "content_block_delta",
181
+ "index" => 0,
182
+ "delta" => { "type" => "text_delta", "text" => tail },
183
+ "cloak_flush" => true
184
+ }
185
+ when :openai
186
+ {
187
+ "object" => "chat.completion.chunk",
188
+ "choices" => [{ "index" => 0, "delta" => { "content" => tail }, "finish_reason" => nil }],
189
+ "cloak_flush" => true
190
+ }
191
+ else
192
+ raise ArgumentError, "unknown stream shape #{shape.inspect} (expected :anthropic or :openai)"
193
+ end
194
+ end
195
+ end
196
+ end
@@ -0,0 +1,233 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloakAPI
4
+ # SURROGATE MODE — the ONE source of truth for this SDK's substitution modes.
5
+ #
6
+ # Faithful Ruby twin of the reference implementation,
7
+ # +sdk/typescript/src/browser/surrogate-mode.ts+ (SDK 1.3.0, commit
8
+ # +efe7760b+), of +sdk/python/cloakapi/surrogate_mode.py+, and of the Rust
9
+ # twins in +packages/cloak-engine-ffi/src/surrogate_mode.rs+.
10
+ #
11
+ # Rolf, 2026-07-28 (DECISIONS.md Decision 11): there are exactly TWO modes,
12
+ # everywhere, forever —
13
+ #
14
+ # * +balanced+ — realistic stand-ins (+John Mellows+ -> +Henry Caulinger+).
15
+ # **The default.**
16
+ # * +max+ — opaque placeholders (+John Mellows+ -> +<<CLOAK:PERSON:1>>+).
17
+ #
18
+ # +continuity+ and +off+ are RETIRED AS CHOICES. The continuity BEHAVIOUR — the
19
+ # same real value maps to the same stand-in for a whole conversation — is
20
+ # ALWAYS ON in BOTH modes, and is never named or offered anywhere. Nobody wants
21
+ # John Mellows to become Henry Caulinger in one turn and Marcus Webb in the
22
+ # next, so offering that as a toggle would only ever be offering a defect.
23
+ #
24
+ # == THE TWO HARD INVARIANTS THIS FILE EXISTS TO ENFORCE
25
+ #
26
+ # 1. A MODE SELECTS STYLE ONLY. No mode value — current, legacy, stored or
27
+ # malformed — may ever gate WHETHER tokenisation happens. In this SDK the
28
+ # mode is a single string threaded into the shared engine's +opts_json+; the
29
+ # engine reads it in exactly ONE function, which runs AFTER every detector
30
+ # and AFTER the coverage assertion, and whose only power is to rewrite an
31
+ # already-detected span's replacement string. There is structurally no code
32
+ # path from a mode string to a skipped detector.
33
+ #
34
+ # This is not a stylistic preference. On the desktop, +tier+ was a GATE —
35
+ # the on-device tokenise call sat behind <tt>tier == "max"</tt>, so the
36
+ # default +balanced+ never tokenised at all and sent person, email, phone,
37
+ # national ID, street and org VERBATIM for two weeks while the UI claimed
38
+ # otherwise. +spec/surrogate_mode_spec.rb+ asserts MAX and BALANCED produce
39
+ # the identical span set.
40
+ #
41
+ # 2. THE MIGRATION FUNCTION IS TOTAL. {coerce} maps EVERY possible input into
42
+ # {MODES}, so a legacy +"continuity"+ or +"off"+ sitting in a consumer's
43
+ # config resolves to a PROTECTED mode. It is structurally impossible for it
44
+ # to return anything else: the only non-default returns are guarded by a
45
+ # membership test against {MODES} itself, and the alias table's values are
46
+ # drawn from that same set.
47
+ #
48
+ # == WHY A CALL SITE RAISES BUT STORAGE COERCES
49
+ #
50
+ # These are different failures and deserve different answers:
51
+ #
52
+ # * <tt>client.messages(..., surrogate_mode: "contnuity")</tt> is a BUG IN LIVE
53
+ # CODE. It raises {Error}, loudly, at the call site.
54
+ # * <tt>SurrogateMode.coerce(config["mode"])</tt> is DATA FROM THE PAST. It
55
+ # resolves to +balanced+ — full protection — silently and always.
56
+ #
57
+ # Neither path can ever produce "no protection".
58
+ #
59
+ # This module is PURE (string constants + total functions, no engine load) so
60
+ # it is safe to require from anywhere at zero cost.
61
+ module SurrogateMode
62
+ # Canonical list — also the picker order (safest, least-disruptive first).
63
+ MODES = %w[balanced max].freeze
64
+
65
+ # The mode used whenever a caller does not choose one. Never "no protection".
66
+ DEFAULT = "balanced"
67
+
68
+ # Scope over which the same real value maps to the same stand-in.
69
+ CONTINUITIES = %w[conversation single-message].freeze
70
+
71
+ # The continuity a tokenise call has when the caller supplied no ledger. The
72
+ # NARROW claim — never the wide one — because a body tokenised without a
73
+ # bindings ledger genuinely cannot promise cross-turn stability.
74
+ DEFAULT_CONTINUITY = "single-message"
75
+
76
+ # Mode values that once existed and may still be sitting in a consumer's
77
+ # config, a saved profile, or an old API request. EVERY one of them resolves
78
+ # to a PROTECTED mode — never to plaintext.
79
+ #
80
+ # 'continuity' -> 'balanced' (its behaviour is now unconditional in both)
81
+ # 'off' -> 'balanced' (there has never been, and will never be, a
82
+ # 'plaintext' -> plaintext posture; the gateway is Level-1-only)
83
+ # 'none' -> 'balanced'
84
+ # 'disabled' -> 'balanced'
85
+ # 'realistic' -> 'balanced'
86
+ # 'token' -> 'max' (the name the client-tier benchmark used)
87
+ # 'opaque' -> 'max'
88
+ # 'strict' -> 'max'
89
+ LEGACY_ALIASES = {
90
+ "continuity" => "balanced",
91
+ "off" => "balanced",
92
+ "plaintext" => "balanced",
93
+ "none" => "balanced",
94
+ "disabled" => "balanced",
95
+ "realistic" => "balanced",
96
+ "token" => "max",
97
+ "opaque" => "max",
98
+ "strict" => "max"
99
+ }.freeze
100
+
101
+ # An explicit call-site +mode+ argument that is not a real mode. Raised by
102
+ # {resolve} ONLY — stored/transported values go through the TOTAL {coerce}
103
+ # and never raise.
104
+ class Error < ArgumentError
105
+ CODE = "invalid-surrogate-mode"
106
+
107
+ def initialize
108
+ super(
109
+ "invalid surrogate mode (invalid-surrogate-mode) — the only modes are " \
110
+ "#{MODES.join(' | ')}. (Legacy stored values should go through " \
111
+ "SurrogateMode.coerce, which migrates them to a protected mode; a " \
112
+ "literal at a call site is a bug and is not silently corrected.)"
113
+ )
114
+ end
115
+ end
116
+
117
+ # True only for one of the two real modes.
118
+ def self.mode?(raw)
119
+ raw.is_a?(String) && MODES.include?(raw)
120
+ end
121
+
122
+ # TOTAL migration for a STORED / TRANSPORTED mode value. Maps ANY input — a
123
+ # current mode, a retired one, +nil+, a number, an object — onto a real,
124
+ # PROTECTED mode.
125
+ #
126
+ # It is structurally impossible for this to return a value outside {MODES}:
127
+ # the only returns other than the default are guarded by a membership test
128
+ # against +MODES+ itself.
129
+ def self.coerce(raw)
130
+ return DEFAULT unless raw.is_a?(String)
131
+
132
+ norm = raw.strip.downcase
133
+ return norm if MODES.include?(norm)
134
+
135
+ alias_mode = LEGACY_ALIASES[norm]
136
+ return alias_mode if alias_mode && MODES.include?(alias_mode)
137
+
138
+ DEFAULT
139
+ end
140
+
141
+ # Resolve an EXPLICIT call-site +mode+ argument.
142
+ # nil -> DEFAULT (the caller did not choose)
143
+ # a real mode -> itself
144
+ # anything else -> raises {Error}
145
+ # Use {coerce} for values that came out of storage or off a wire instead.
146
+ def self.resolve(raw)
147
+ return DEFAULT if raw.nil?
148
+ return raw if mode?(raw)
149
+
150
+ raise Error
151
+ end
152
+
153
+ # TOTAL coercion for a STORED / TRANSPORTED continuity value.
154
+ #
155
+ # Unknown input NARROWS to +single-message+. This asymmetry is deliberate:
156
+ # +conversation+ is the STRONGER claim made to the upstream model ("they are
157
+ # stable within this conversation"), so it is only ever returned when the
158
+ # engine explicitly said so. A malformed value must never be upgraded into a
159
+ # promise the bytes cannot keep.
160
+ def self.coerce_continuity(raw)
161
+ return DEFAULT_CONTINUITY unless raw.is_a?(String)
162
+
163
+ norm = raw.strip.downcase
164
+ CONTINUITIES.include?(norm) ? norm : DEFAULT_CONTINUITY
165
+ end
166
+
167
+ # What a tokenise pass ACTUALLY did — a REQUIRED field on every tokenise
168
+ # result.
169
+ #
170
+ # Deliberately not optional and carrying no default. The precedent is
171
+ # +ner_degraded+: computed honestly, transported, parsed, and then never read
172
+ # by anything — which is how raw PII egressed while the extension recorded
173
+ # <tt>outcomeReason: 'tokenised'</tt>. **An optional signal is a signal that
174
+ # gets dropped.** +Data.define+ makes both members REQUIRED keywords, so a
175
+ # hand-written fake result raises +ArgumentError: missing keyword+ at
176
+ # construction — which is exactly the intent.
177
+ #
178
+ # mode — the mode the caller asked for (or the default).
179
+ # continuity — whether the stand-ins are stable for a whole CONVERSATION
180
+ # (a bindings ledger was supplied) or only within THIS
181
+ # message. The disclosure text is selected from this, so the
182
+ # claim made to the model is only ever the claim the bytes
183
+ # can support.
184
+ Report = Data.define(:mode, :continuity) do
185
+ # TOTAL parse of the engine's +surrogate_mode+ object. Never raises and
186
+ # never widens: a missing/garbled payload yields +balanced+ +
187
+ # +single-message+ — full protection, narrow claim.
188
+ def self.from_payload(raw)
189
+ if raw.is_a?(Hash)
190
+ new(
191
+ mode: SurrogateMode.coerce(raw["mode"] || raw[:mode]),
192
+ continuity: SurrogateMode.coerce_continuity(raw["continuity"] || raw[:continuity])
193
+ )
194
+ else
195
+ new(mode: DEFAULT, continuity: DEFAULT_CONTINUITY)
196
+ end
197
+ end
198
+ end
199
+
200
+ # User-facing copy shown AT THE POINT OF CHOICE. Each mode states a REAL
201
+ # cost — neither is marketed over the other, because the honest answer is
202
+ # that both trade something. The word "continuity" appears nowhere; the
203
+ # always-on behaviour is described plainly in {SHARED_NOTE} instead, once,
204
+ # under both options.
205
+ Copy = Data.define(:label, :short, :tradeoff)
206
+
207
+ COPY = {
208
+ "balanced" => Copy.new(
209
+ label: "Balanced",
210
+ short: "Realistic stand-ins — John Mellows becomes Henry Caulinger.",
211
+ tradeoff: "The model cannot tell the stand-ins are fake, so it may reason about them " \
212
+ "as if they were real — drawing conclusions from a substituted name, or " \
213
+ "treating a substituted address as a genuine place."
214
+ ),
215
+ "max" => Copy.new(
216
+ label: "Max",
217
+ short: "Opaque placeholders — John Mellows becomes <<CLOAK:PERSON:1>>.",
218
+ tradeoff: "The model can see the value is hidden, so it may write awkwardly around " \
219
+ "the placeholder, ask you for the real value, or decline to continue."
220
+ )
221
+ }.freeze
222
+
223
+ # Shown ONCE, under both modes. Never uses the word "continuity".
224
+ SHARED_NOTE = "Either way, the same detail always maps to the same replacement for the " \
225
+ "whole conversation, and the real values are restored in the reply on your " \
226
+ "device."
227
+
228
+ # Copy for a mode. TOTAL — coerces, so a picker can never render nothing.
229
+ def self.copy(mode)
230
+ COPY.fetch(coerce(mode))
231
+ end
232
+ end
233
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloakAPI
4
+ # The version of this gem, also sent as +User-Agent: cloakapi-ruby/<version>+.
5
+ #
6
+ # 1.4.1 belongs to release set R-1.6.1: it is built for rule set 1.6.1
7
+ # (+CloakAPI::Engine::RULESET_VERSION+) and accepts the two native engine
8
+ # builds that set names (+CloakAPI::Engine::RELEASE_SET_NATIVE+). To see what
9
+ # is actually running:
10
+ #
11
+ # CloakAPI::VERSION # => "1.4.1"
12
+ # CloakAPI::Engine::RULESET_VERSION # => "1.6.1"
13
+ # CloakAPI::Engine.status # engine used or not, and why
14
+ VERSION = "1.4.1"
15
+ end
@@ -0,0 +1,137 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloakAPI
4
+ # How much of the SDK's detection ran for a piece of text or a request.
5
+ #
6
+ # full - the on-device engine with its name model
7
+ # rules_and_names - the on-device engine without the name model
8
+ # rules_only - the SDK's built-in rules (no engine)
9
+ module Coverage
10
+ FULL = "full"
11
+ RULES_AND_NAMES = "rules_and_names"
12
+ RULES_ONLY = "rules_only"
13
+ ORDER = [FULL, RULES_AND_NAMES, RULES_ONLY].freeze
14
+
15
+ # The weaker of two coverage values; an unknown value counts as the weakest.
16
+ def self.weakest(a, b)
17
+ return b if a.nil?
18
+ return a if b.nil?
19
+
20
+ (ORDER.index(a) || ORDER.length) >= (ORDER.index(b) || ORDER.length) ? a : b
21
+ end
22
+ end
23
+
24
+ # One non-blocking notice. +code+ and +reason+ are fixed identifiers;
25
+ # +message+ is plain English and never holds text from the request.
26
+ #
27
+ # reduced_coverage - engine_missing, engine_unloadable, pin_missing,
28
+ # pin_mismatch, ruleset_mismatch, model_missing
29
+ # unchecked_content - unverified_script, value_not_replaced, media_not_checked,
30
+ # unrecognised_block
31
+ SendWarning = Data.define(:code, :reason, :message) do
32
+ def to_h = { "code" => code, "reason" => reason, "message" => message }
33
+ def to_s = "#{code} (#{reason}): #{message}"
34
+ end
35
+
36
+ # What the review callback receives next to the outgoing text.
37
+ #
38
+ # state - "ok" or "degraded"
39
+ # coverage - a CloakAPI::Coverage value
40
+ # warnings - Array of CloakAPI::SendWarning
41
+ ReviewInfo = Data.define(:state, :coverage, :warnings) do
42
+ def degraded? = state != "ok"
43
+ def to_h = { "state" => state, "coverage" => coverage, "warnings" => warnings.map(&:to_h) }
44
+ end
45
+
46
+ # Raised before any network call when a request has not been approved: no
47
+ # review callback was given, the callback declined, or +create+ was handed
48
+ # something other than an approved request. An ArgumentError subclass because
49
+ # that is what the same situation raised before 1.4.0.
50
+ class ReviewRequiredError < ArgumentError
51
+ def code = "review_required"
52
+ end
53
+
54
+ # The decoded reply of a send, with the detection state of the request that
55
+ # produced it. Behaves as the Hash it always was.
56
+ class Response < Hash
57
+ attr_reader :coverage, :warnings
58
+
59
+ def self.wrap(hash, coverage:, warnings:)
60
+ return hash unless hash.is_a?(Hash)
61
+
62
+ out = new
63
+ out.replace(hash)
64
+ out.instance_variable_set(:@coverage, coverage)
65
+ out.instance_variable_set(:@warnings, warnings.dup.freeze)
66
+ out
67
+ end
68
+ end
69
+
70
+ # Builds the notices and writes them to the standard error stream.
71
+ module Warnings
72
+ REDUCED = "reduced_coverage"
73
+ UNCHECKED = "unchecked_content"
74
+
75
+ MODEL_MISSING_MESSAGE =
76
+ "The CloakAPI name model is not available, so names are detected from the engine's built-in lists only; " \
77
+ "some names may be sent as written."
78
+ UNVERIFIED_SCRIPT_MESSAGE =
79
+ "The request contains text in a script this device cannot check (for example Thai or Khmer). " \
80
+ "It is sent as written."
81
+ VALUE_NOT_REPLACED_MESSAGE =
82
+ "A final local check found a value that looks like personal data in a part of the request that " \
83
+ "was not replaced. It is sent as written."
84
+ # Sentences of the cross-SDK value-placement rule (same in every SDK).
85
+ NUMBER_MESSAGE =
86
+ "A number looks like personal data. A number cannot be replaced without changing its type, " \
87
+ "so it was not replaced. It is sent as written."
88
+ MEDIA_MESSAGE =
89
+ "This request includes an image, audio clip or file that this device did not read. It is sent as provided."
90
+ IDENTIFIER_MESSAGE =
91
+ "An identifier field looks like personal data. Identifiers must stay as they are, so it was not replaced. It is sent as written."
92
+ UNKNOWN_BLOCK_MESSAGE =
93
+ "This request includes a content block of a type this SDK does not know. Its text was checked like other text and it is sent."
94
+ ARGUMENT_KEY_MESSAGE =
95
+ "A key inside tool-call arguments looks like personal data. Keys there follow the tool's schema, so it was not replaced. It is sent as written."
96
+ PARTIAL_SCAN_MESSAGE =
97
+ "Detection was partial for this text (it is very large or holds bytes that are not valid text). " \
98
+ "Some values may be sent as written."
99
+
100
+ @mutex = Mutex.new
101
+ @seen = {}
102
+
103
+ class << self
104
+ def reduced(reason, message) = SendWarning.new(code: REDUCED, reason: reason.to_s, message: message.to_s)
105
+ def unchecked(reason, message) = SendWarning.new(code: UNCHECKED, reason: reason.to_s, message: message.to_s)
106
+
107
+ # Same code and reason is the same notice; keep the first.
108
+ def merge(*lists)
109
+ lists.flatten.compact.uniq { |warning| [warning.code, warning.reason] }
110
+ end
111
+
112
+ # One line per notice. Reduced coverage is written once per process for
113
+ # each reason; unchecked content is written every time (once per send).
114
+ def emit(warning, once: warning.code == REDUCED)
115
+ if once
116
+ first = @mutex.synchronize do
117
+ key = [warning.code, warning.reason]
118
+ seen = @seen.key?(key)
119
+ @seen[key] = true
120
+ !seen
121
+ end
122
+ return unless first
123
+ end
124
+ begin
125
+ Kernel.warn("cloakapi: warning #{warning.code} (#{warning.reason}): #{warning.message}")
126
+ rescue StandardError
127
+ nil # reporting never breaks the call it reports on
128
+ end
129
+ end
130
+
131
+ # Test hook: forget which once-per-process notices were written.
132
+ def reset_for_tests!
133
+ @mutex.synchronize { @seen.clear }
134
+ end
135
+ end
136
+ end
137
+ end
data/lib/cloakapi.rb ADDED
@@ -0,0 +1,37 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "cloakapi/version"
4
+ require_relative "cloakapi/errors"
5
+ require_relative "cloakapi/warnings"
6
+ require_relative "cloakapi/surrogate_mode"
7
+ require_relative "cloakapi/engine"
8
+ require_relative "cloakapi/degraded"
9
+ require_relative "cloakapi/pii/ruleset"
10
+ require_relative "cloakapi/pii/pii_type"
11
+ require_relative "cloakapi/pii/pii_match"
12
+ require_relative "cloakapi/pii/detector"
13
+ require_relative "cloakapi/pii/bundled_rules"
14
+ require_relative "cloakapi/pii/tokenizer"
15
+ require_relative "cloakapi/disclosure"
16
+ require_relative "cloakapi/receipts"
17
+ require_relative "cloakapi/posture"
18
+ require_relative "cloakapi/streaming"
19
+ require_relative "cloakapi/routing"
20
+ require_relative "cloakapi/client"
21
+ require_relative "cloakapi/resources/messages"
22
+ require_relative "cloakapi/resources/chat"
23
+ require_relative "cloakapi/resources/models"
24
+ require_relative "cloakapi/resources/tokens"
25
+ require_relative "cloakapi/resources/receipts"
26
+ require_relative "cloakapi/resources/reconstruct"
27
+
28
+ # CloakAPI Ruby SDK — privacy-first LLM gateway client.
29
+ #
30
+ # client = CloakAPI::Client.new("cloak_abc123")
31
+ # resp = client.messages.create(
32
+ # model: "claude-sonnet-4-6",
33
+ # messages: [{ role: "user", content: "Hello!" }]
34
+ # )
35
+ # puts resp["content"][0]["text"]
36
+ module CloakAPI
37
+ end