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.
- 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/_lib/linux-x86_64/libcloak_engine.so +0 -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 +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
|