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
data/README.md
ADDED
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
# CloakAPI Ruby SDK
|
|
2
|
+
|
|
3
|
+
Ruby client for the [CloakAPI](https://cloakapi.io) gateway. Before a request
|
|
4
|
+
leaves your machine, the SDK replaces the personal data it detects in the text
|
|
5
|
+
with stand-ins, shows you the exact text that will be sent, and after the reply
|
|
6
|
+
comes back puts the original values in again, locally. A value the SDK does not
|
|
7
|
+
detect is sent as written, so the review step matters.
|
|
8
|
+
|
|
9
|
+
- Ruby 3.2 or newer (tested on 3.2 and 4.0). No runtime gem dependencies, no compiler.
|
|
10
|
+
- Works on Linux, macOS and Windows. The optional native engine exists for
|
|
11
|
+
Linux (x86-64 and aarch64, glibc 2.39 or newer) only; see [Platforms](#platforms).
|
|
12
|
+
- Licence: Apache-2.0.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
gem install --local cloakapi-1.4.1.gem # the gem file
|
|
18
|
+
# or, in a Gemfile: gem "cloakapi", "~> 1.4"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Hello world
|
|
22
|
+
|
|
23
|
+
```ruby
|
|
24
|
+
require "cloakapi"
|
|
25
|
+
|
|
26
|
+
# The review callback gets the exact outgoing text and the detection state.
|
|
27
|
+
# Return true to send, false to stop. Nothing is sent before it returns true.
|
|
28
|
+
review = lambda do |text, info|
|
|
29
|
+
puts text
|
|
30
|
+
info.warnings.each { |warning| warn "note: #{warning.message}" }
|
|
31
|
+
true
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
client = CloakAPI::Client.new(ENV.fetch("CLOAKAPI_API_KEY"), review: review)
|
|
35
|
+
reply = client.messages.create(
|
|
36
|
+
model: "claude-sonnet-4-6",
|
|
37
|
+
max_tokens: 200,
|
|
38
|
+
messages: [{ role: "user", content: "Write a one-line reply to jane.roe@example.com" }]
|
|
39
|
+
)
|
|
40
|
+
puts reply["content"][0]["text"] # the address is back in the reply
|
|
41
|
+
puts reply.coverage # "full", "rules_and_names" or "rules_only"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
What the callback sees for the message above, without the native engine:
|
|
45
|
+
`... "content":"Write a one-line reply to <<CLOAK:EMAIL:f3a1c2>>" ...`.
|
|
46
|
+
|
|
47
|
+
`examples/hello.rb` is this program with a yes/no prompt. It runs without a key
|
|
48
|
+
against the small stand-in gateway in `examples/fake_gateway.rb`:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
ruby examples/fake_gateway.rb 8787 &
|
|
52
|
+
CLOAKAPI_API_KEY=test CLOAKAPI_BASE_URL=http://127.0.0.1:8787 ruby examples/hello.rb
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**What the gateway answers.** A request prepared with the native engine and
|
|
56
|
+
its pin (next section) carries the engine's identity. A request prepared by
|
|
57
|
+
the built-in rules says so (`coverage=rules_only`) and carries no engine
|
|
58
|
+
identity. A gateway that requires an engine identity answers such a request
|
|
59
|
+
with HTTP 428 (`engine_identity_required`), which the SDK raises as
|
|
60
|
+
`CloakAPI::ApiError` with `status_code` 428; a gateway that accepts declared
|
|
61
|
+
rules-only requests relays it, and the receipt then states that no engine was
|
|
62
|
+
verified. If you get 428 on macOS, Windows, Alpine or an older Linux, that is
|
|
63
|
+
this: the request was built correctly and the gateway you reached asks for the
|
|
64
|
+
engine.
|
|
65
|
+
|
|
66
|
+
## The review step
|
|
67
|
+
|
|
68
|
+
Every `messages` and `chat.completions` request is reviewed before it is sent.
|
|
69
|
+
There are two forms of the same thing.
|
|
70
|
+
|
|
71
|
+
**Callback form.** Give the client (or one call) a `review:` callable. It is
|
|
72
|
+
called with `(text, info)`: `text` is the exact request body, `info` is a
|
|
73
|
+
`CloakAPI::ReviewInfo` with `state` (`"ok"` or `"degraded"`), `coverage` and
|
|
74
|
+
`warnings`. A true return value sends. A false or `nil` return value, or no
|
|
75
|
+
callback at all, raises `CloakAPI::ReviewRequiredError` before any network call.
|
|
76
|
+
A server that has nobody to show the text to can pass `review: ->(_text, _info) { true }`.
|
|
77
|
+
|
|
78
|
+
**Step form.**
|
|
79
|
+
|
|
80
|
+
```ruby
|
|
81
|
+
prepared = client.messages.prepare(model: "claude-sonnet-4-6", messages: messages)
|
|
82
|
+
prepared.text # the exact outgoing body (also: prepared.preview)
|
|
83
|
+
prepared.coverage # "rules_only", ...
|
|
84
|
+
prepared.warnings # [#<CloakAPI::SendWarning code="reduced_coverage" reason="engine_missing" message="...">]
|
|
85
|
+
approved = client.approve(prepared) # or prepared.approve
|
|
86
|
+
reply = client.messages.create(approved) # send_approved(approved) is the same call
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
An approval is for one send of exactly those bytes. Changing the body or the
|
|
90
|
+
headers, using an approval twice, or using one from another client raises
|
|
91
|
+
before anything is sent.
|
|
92
|
+
|
|
93
|
+
### What can stop a request, and what cannot
|
|
94
|
+
|
|
95
|
+
The content of a request never stops it. If the engine is missing or cannot be
|
|
96
|
+
used, if text is in a script the SDK cannot check (for example Thai), or if a
|
|
97
|
+
value could not be replaced, the request is still sent and you get a warning in
|
|
98
|
+
three places: on `info` / `prepared.warnings` before you approve, on
|
|
99
|
+
`reply.warnings` afterwards, and as one line on standard error
|
|
100
|
+
(`cloakapi: warning reduced_coverage (engine_missing): ...`; reduced coverage
|
|
101
|
+
once per process, unchecked content once per send).
|
|
102
|
+
|
|
103
|
+
| `code` | `reason` | Meaning |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| `reduced_coverage` | `engine_missing`, `engine_unloadable`, `pin_missing`, `pin_mismatch`, `ruleset_mismatch` | The native engine is not in use; the built-in rules are |
|
|
106
|
+
| `reduced_coverage` | `model_missing` | The engine runs without its name model |
|
|
107
|
+
| `unchecked_content` | `unverified_script` | Text in a script the SDK cannot check is sent as written |
|
|
108
|
+
| `unchecked_content` | `value_not_replaced` | Something that looks like personal data remains where it cannot be replaced: a JSON number (a number stays a number), a key inside tool-call arguments or a tool definition, an identifier. A key in other free-form data is replaced with a stand-in where it stands; a key in `metadata` stays as written, without a warning (owner decision F-068) |
|
|
109
|
+
| `unchecked_content` | `media_not_checked` | The request includes an image, audio clip or file (inline bytes, a `data:` URL, a file reference) that this device did not read; it is sent as provided. A document whose source is plain text (`"type": "text"`) is not media: its text is tokenised |
|
|
110
|
+
| `unchecked_content` | `unrecognised_block` | The request includes a content block of a type this SDK does not know (for example `search_result`); every string in it outside protocol fields was checked like other text, and it is sent |
|
|
111
|
+
|
|
112
|
+
What does stop a request: no review or a declined review, a wrong key, balance
|
|
113
|
+
or quota, a request the gateway or provider rejects, a body that is not a
|
|
114
|
+
valid request (a content block that is not an object or has an unknown type,
|
|
115
|
+
a value that cannot be serialised), text that already contains a
|
|
116
|
+
`<<CLOAK:...>>` marker, and network errors.
|
|
117
|
+
|
|
118
|
+
An image or file inside a request is not read by the request path: it leaves
|
|
119
|
+
as you provided it, and the warning is the only thing the reviewer sees about
|
|
120
|
+
it. To have a document or image read and its text replaced on your machine,
|
|
121
|
+
use `tokenize_file` (below) and send the text it returns.
|
|
122
|
+
|
|
123
|
+
If you would rather have reduced detection refuse a request, say so explicitly:
|
|
124
|
+
`CloakAPI::Client.new(key, strict_coverage: true)` raises
|
|
125
|
+
`CloakAPI::Degraded::ReducedCoverageError` instead of sending. It is off by
|
|
126
|
+
default. (`CLOAKAPI_ALLOW_REDUCED=0` in the environment does the same for a
|
|
127
|
+
whole process; it is not set unless you set it.)
|
|
128
|
+
|
|
129
|
+
## Platforms
|
|
130
|
+
|
|
131
|
+
| System | What you get |
|
|
132
|
+
|---|---|
|
|
133
|
+
| Linux x86-64 or aarch64, glibc 2.39+ (Debian 13, Ubuntu 24.04, ...) | Native engine if you configure it; otherwise the built-in rules |
|
|
134
|
+
| Linux with an older glibc (Debian 12, Ubuntu 22.04, ...) | Built-in rules. With an engine configured: warning `engine_unloadable`, "The engine needs glibc 2.39 or newer (this system has glibc 2.36)" |
|
|
135
|
+
| Alpine and other musl systems | Built-in rules. With an engine configured: warning `engine_unloadable`, "this system uses musl, which is not supported" |
|
|
136
|
+
| macOS, Windows | Built-in rules (warning `engine_missing`) |
|
|
137
|
+
|
|
138
|
+
The built-in rules run every rule type of the rule set that comes with the gem
|
|
139
|
+
and has a pattern: 139 of its 142 types (email addresses, phone numbers, card
|
|
140
|
+
numbers, IBANs and other account numbers, national ID numbers of many
|
|
141
|
+
countries with their check digits, dates of birth, postcodes, street
|
|
142
|
+
addresses, IP addresses, API keys and more). The three types without a pattern
|
|
143
|
+
are NAME, PLACE and ORGANIZATION: they need the engine's name model, so the
|
|
144
|
+
built-in rules do not recognise names, and a name is sent as written unless
|
|
145
|
+
the native engine is in use. Two of the rule types are broad on purpose and also
|
|
146
|
+
replace things that are not personal data: any date can be taken for a date of
|
|
147
|
+
birth, and a long run of digits (an invoice number, a measurement) for a phone
|
|
148
|
+
number. The reply is restored either way, so your user sees the original text;
|
|
149
|
+
the model sees the stand-in. With the native engine, detection is done by the
|
|
150
|
+
engine instead, and with its name model it also covers names; neither finds
|
|
151
|
+
everything.
|
|
152
|
+
|
|
153
|
+
Time: the built-in rules take about 1 ms for a short message, about 10 ms per
|
|
154
|
+
kilobyte and about half a second for 50 kB of text. A text that would take more
|
|
155
|
+
than two seconds is cut short: the request is sent with what was found and a
|
|
156
|
+
warning (`unchecked_content`).
|
|
157
|
+
|
|
158
|
+
## The native engine and its pin
|
|
159
|
+
|
|
160
|
+
The engine is one shared library (`libcloak_engine.so`), loaded through Ruby's
|
|
161
|
+
`fiddle`. Download it, check its SHA-256, and tell the SDK where it is and
|
|
162
|
+
which file you expect:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
export CLOAKAPI_ENGINE_LIB=/opt/cloakapi/libcloak_engine.so
|
|
166
|
+
export CLOAKAPI_ENGINE_SHA256_PIN=$(sha256sum "$CLOAKAPI_ENGINE_LIB" | cut -d' ' -f1)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
One rule decides whether the engine is used:
|
|
170
|
+
|
|
171
|
+
- `CLOAKAPI_ENGINE_LIB` set and `CLOAKAPI_ENGINE_SHA256_PIN` equal to the
|
|
172
|
+
SHA-256 of that file, and the file is an engine for this SDK's rule set
|
|
173
|
+
(1.6.1): the engine is used. The SDK reads the file once, checks the hash of
|
|
174
|
+
those bytes and loads a private copy of the same bytes.
|
|
175
|
+
- Anything else (no pin, a malformed or different pin, a file that is missing,
|
|
176
|
+
cannot be loaded or is built for another rule set): the engine is **not**
|
|
177
|
+
used. The SDK continues on its built-in rules and the warning names the
|
|
178
|
+
reason, for example `CLOAKAPI_ENGINE_SHA256_PIN is not set, so the engine at
|
|
179
|
+
CLOAKAPI_ENGINE_LIB was not used.` It never raises for this.
|
|
180
|
+
|
|
181
|
+
`CloakAPI::Engine.status` tells you what was decided (`used?`, `reason`,
|
|
182
|
+
`message`). The decision is made once per process.
|
|
183
|
+
|
|
184
|
+
Notes:
|
|
185
|
+
|
|
186
|
+
- On Ruby 3.5 and newer `fiddle` is a bundled gem. In an application with a
|
|
187
|
+
Gemfile, add `gem "fiddle"` or the engine cannot be loaded
|
|
188
|
+
(`engine_unloadable`; the SDK still works on its built-in rules).
|
|
189
|
+
- The private copy is written under `TMPDIR`. If that directory is mounted
|
|
190
|
+
`noexec`, the engine cannot be loaded; point `TMPDIR` at one that allows it.
|
|
191
|
+
- The name model is a separate download. Because the SDK loads a private copy
|
|
192
|
+
of the engine, a model placed next to the engine file is not found: name it
|
|
193
|
+
with `CLOAKAPI_NER_MODEL_PATH` and `CLOAKAPI_NER_TOKENIZER_PATH`. Set
|
|
194
|
+
`CLOAKAPI_NER_MODEL_PATH` to the file you trust. Engine 1.6.1, when that
|
|
195
|
+
variable is unset, also searches a path compiled in from the build host under
|
|
196
|
+
`/tmp` and every parent directory of the working directory and of the
|
|
197
|
+
executable. A model placed on one of those paths is loaded. Without the model
|
|
198
|
+
the engine still runs (`coverage` is `rules_and_names`, warning `model_missing`).
|
|
199
|
+
- A platform build of this gem can carry the engine file itself; then no
|
|
200
|
+
variable is needed. The default gem does not.
|
|
201
|
+
|
|
202
|
+
## Threads
|
|
203
|
+
|
|
204
|
+
A client is one conversation: it remembers which stand-in belongs to which
|
|
205
|
+
value so that the same value keeps the same stand-in across turns, and it uses
|
|
206
|
+
that memory to restore replies. One client may be used from several threads;
|
|
207
|
+
calls that read or change that memory run one at a time, in the order they
|
|
208
|
+
arrive, and every prepared request carries its own coverage, warnings and
|
|
209
|
+
restore map. `last_detection_status` and `last_surrogate_mode` describe the
|
|
210
|
+
most recent call on the client, whichever thread made it; under threads read
|
|
211
|
+
the state from the prepared request or the reply instead.
|
|
212
|
+
|
|
213
|
+
In a web application, create a client per user conversation (it is cheap)
|
|
214
|
+
rather than one client for the whole process: a process-wide client would keep
|
|
215
|
+
every user's values in one growing memory for as long as the process lives.
|
|
216
|
+
The engine itself is loaded once per process and shared.
|
|
217
|
+
|
|
218
|
+
## Files and images
|
|
219
|
+
|
|
220
|
+
File and image handling is opt-in through `Client#tokenize_file`. That call
|
|
221
|
+
turns a document or image into tokenised Markdown on your machine. It needs
|
|
222
|
+
the native engine: without one it raises `CloakAPI::Engine::EngineError` and
|
|
223
|
+
nothing is sent. Text requests do not read file bytes.
|
|
224
|
+
|
|
225
|
+
```ruby
|
|
226
|
+
data = File.binread("intake.png")
|
|
227
|
+
result = client.tokenize_file(data, mime: "image/png", filename: "intake.png")
|
|
228
|
+
# result["text"] tokenised Markdown, the only part meant to be sent
|
|
229
|
+
# result["token_map"] stand-in => original, stays in this process
|
|
230
|
+
prepared = client.messages.prepare(
|
|
231
|
+
model: "claude-sonnet-4-6",
|
|
232
|
+
messages: [{ role: "user", content: "Summarise this form:\n\n#{result["text"]}" }]
|
|
233
|
+
)
|
|
234
|
+
reply = client.messages.create(prepared.approve)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
On `tokenize_file`, supported, decodable images are passed to the on-device engine for OCR.
|
|
238
|
+
Images (PNG, JPEG, WebP, GIF, BMP, TIFF) are read with on-device OCR; PDF,
|
|
239
|
+
DOCX, XLSX, PPTX, CSV and HTML are extracted. The engine may refuse a file it
|
|
240
|
+
cannot read (encrypted, unsupported, damaged); that raises `EngineError`.
|
|
241
|
+
|
|
242
|
+
### Known limitation: JSON tool-call arguments
|
|
243
|
+
|
|
244
|
+
Tool-argument JSON numbers keep their numeric type. If the final local check
|
|
245
|
+
sees a number that looks like personal data, it warns (`value_not_replaced`)
|
|
246
|
+
and the request is still sent. If the tool accepts a string, pass
|
|
247
|
+
`{"card":"4111111111111111"}`: a string can be replaced.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Name detection and the neural model
|
|
252
|
+
|
|
253
|
+
Person names are detected in two layers. Structured identifiers (emails, phones,
|
|
254
|
+
cards, government IDs) use deterministic detectors and do not need this model.
|
|
255
|
+
|
|
256
|
+
- **Built-in name list (on by default).** A compiled-in dictionary. No extra
|
|
257
|
+
download. Uncommon names, surnames alone, and non-Latin scripts may be missed.
|
|
258
|
+
- **On-device neural model (a separate download).** Download it and point
|
|
259
|
+
`CLOAKAPI_NER_MODEL_PATH` and `CLOAKAPI_NER_TOKENIZER_PATH` at the files. If it is unavailable, standard text handling warns
|
|
260
|
+
and continues with available rules; explicit strict mode can refuse reduced
|
|
261
|
+
coverage.
|
|
262
|
+
|
|
263
|
+
Download and verify the engine and name model on
|
|
264
|
+
[Engine setup](https://docs.cloakapi.io/start/engine-setup/).
|
|
265
|
+
|
|
266
|
+
When the model loaded, the result reports `ner_enabled: true`. When it did not,
|
|
267
|
+
some names may remain in the text; standard mode warns and continues, while
|
|
268
|
+
explicit strict mode can refuse reduced coverage.
|
|
269
|
+
|
|
270
|
+
Name detection is best-effort, not exhaustive. Tokenised output is not
|
|
271
|
+
anonymised data: this SDK does not provide HIPAA Safe Harbor de-identification,
|
|
272
|
+
does not make content "PHI-free", and does not render text anonymous. Treat
|
|
273
|
+
tokenisation as on-device minimisation of PII before egress, and keep your own
|
|
274
|
+
review where a residual name would be material.
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Secrets are tokenised + flagged, not blocked
|
|
279
|
+
|
|
280
|
+
A secrets-class value — an API key, payment card, IBAN, national ID or passport —
|
|
281
|
+
is **tokenised and flagged**, exactly like any other entity, not rejected. A
|
|
282
|
+
credential such as `sk-proj-…` becomes `<<CLOAK:CRED_KEY:…>>` (engine) or
|
|
283
|
+
`<<CLOAK:API_KEY:…>>` (built-in rules) and the call returns normally.
|
|
284
|
+
`EngineError` is for a file the engine cannot process (encrypted, unsupported,
|
|
285
|
+
damaged); a secret in the text does not raise it.
|
|
286
|
+
|
|
287
|
+
## Streaming
|
|
288
|
+
|
|
289
|
+
Prepare with `stream: true`, inspect and approve the preview, then call
|
|
290
|
+
`create_stream` with the approved request (or call `create_stream(model:, messages:)`
|
|
291
|
+
on a client that has a review callback). Reply text is de-tokenised
|
|
292
|
+
**on-device across chunk boundaries** — a `<<CLOAK:…>>` token split across two
|
|
293
|
+
SSE frames is reassembled before it reaches your code.
|
|
294
|
+
|
|
295
|
+
```ruby
|
|
296
|
+
stream_preview = client.chat.completions.prepare(
|
|
297
|
+
model: "gpt-4o",
|
|
298
|
+
messages: [{ role: "user", content: "Draft a reply to jane.roe@example.com" }],
|
|
299
|
+
stream: true
|
|
300
|
+
)
|
|
301
|
+
partial_text = +""
|
|
302
|
+
begin
|
|
303
|
+
client.chat.completions.create_stream(stream_preview.approve) do |chunk|
|
|
304
|
+
partial_text << chunk.dig("choices", 0, "delta", "content").to_s # restored locally
|
|
305
|
+
end
|
|
306
|
+
rescue CloakAPI::ApiError
|
|
307
|
+
# partial_text is the answer collected before a quota or gateway error frame.
|
|
308
|
+
raise
|
|
309
|
+
end
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
## Device receipts (on-device, offline-verifiable)
|
|
313
|
+
|
|
314
|
+
Sign a **content-free** ECDSA-P256 device receipt on-device (hashes + counts +
|
|
315
|
+
category labels only — never text) and verify it fully offline. The public key is
|
|
316
|
+
embedded, so verification shows the receipt was not altered after signing; it does not
|
|
317
|
+
show who signed it. Compare the embedded key with the one you expect if origin matters.
|
|
318
|
+
|
|
319
|
+
```ruby
|
|
320
|
+
key = CloakAPI::Receipts.generate_device_key_pair
|
|
321
|
+
receipt = CloakAPI::Receipts.sign_device_receipt(
|
|
322
|
+
entity_count: 3, categories: %w[EMAIL PERSON FIN_CC],
|
|
323
|
+
engine_version: CloakAPI::Engine.identity[0], engine_hash: CloakAPI::Engine.identity[1],
|
|
324
|
+
key: key
|
|
325
|
+
)
|
|
326
|
+
res = CloakAPI::Receipts.verify_receipt(receipt, CloakAPI::Receipts.public_key_hex(key))
|
|
327
|
+
res.ok # => true
|
|
328
|
+
res.kind # => "pass"
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
`CloakAPI::Receipts.verify_chain_links(entries)` walks an ordered receipt-chain
|
|
332
|
+
export offline (dense `seq` + `prev_hash` links).
|
|
333
|
+
|
|
334
|
+
## Disclosure injection
|
|
335
|
+
|
|
336
|
+
On the blind-relay path the gateway injects **no** system prompt, so the client
|
|
337
|
+
prepends the byte-locked cloak-disclosure so the upstream model treats
|
|
338
|
+
placeholders as real values. Applied before the MAC (so it is MAC-covered),
|
|
339
|
+
idempotent and fail-safe.
|
|
340
|
+
|
|
341
|
+
```ruby
|
|
342
|
+
body = CloakAPI::Disclosure.with_disclosure(
|
|
343
|
+
{ "messages" => [{ "role" => "user", "content" => "…" }] },
|
|
344
|
+
# Required. Pass the scope from the tokenise result ("conversation" or "single-message").
|
|
345
|
+
continuity: "conversation",
|
|
346
|
+
format: "cloak-angle" # the <<CLOAK:…>> family the FFI engine emits
|
|
347
|
+
)
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Trust, discovery & routing resources
|
|
351
|
+
|
|
352
|
+
```ruby
|
|
353
|
+
receipt_review = client.receipts.prepare_verify(receipt)
|
|
354
|
+
client.receipts.verify(receipt_review.approve) # POST after local review
|
|
355
|
+
client.receipts.get(jti) # GET /api/v1/receipts/by-jti/{jti}
|
|
356
|
+
client.receipts.list(page: 1) # GET /api/v1/receipts
|
|
357
|
+
client.receipts.verify_offline(r, public_key_hex: pk) # pure, no network
|
|
358
|
+
|
|
359
|
+
client.models.list # GET /api/v1/models (live catalogue)
|
|
360
|
+
# tokens.count is intentionally unavailable: the gateway's route returns 410,
|
|
361
|
+
# and the SDK will not send prompt content for server-side token counting.
|
|
362
|
+
# Use your provider's tokenizer locally if you need a count.
|
|
363
|
+
|
|
364
|
+
# Local reconstruction uses the supplied alias map in this process; the caller
|
|
365
|
+
# controls whether that map is sent elsewhere.
|
|
366
|
+
client.reconstruct.create(response_text: reply, alias_map: map, target_format: "md")
|
|
367
|
+
|
|
368
|
+
# Client-side arbitrage routing (the gateway does NO content classification):
|
|
369
|
+
route = client.router.resolve(messages, "openai", "gpt-4o")
|
|
370
|
+
# route => { "provider" =>, "model" =>, "strategy" =>, "routed_client_side" => true }
|
|
371
|
+
|
|
372
|
+
# A content-free description of this integration:
|
|
373
|
+
client.privacy_posture # engine identity, tiers, detectors
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
Receipt verify and countersign accept content-free receipt envelope fields only.
|
|
377
|
+
Unknown fields and free-text values are rejected before a review preview is
|
|
378
|
+
issued; do not put prompts or other user content in receipt claims.
|
|
379
|
+
|
|
380
|
+
### Continuity seed (`seed_hex`)
|
|
381
|
+
|
|
382
|
+
Pass `seed_hex:` to `messages.prepare` / `chat.completions.prepare` to give the
|
|
383
|
+
engine a continuity seed for **cross-session stable stand-ins** (forward-safe: an
|
|
384
|
+
older engine ignores it).
|
|
385
|
+
|
|
386
|
+
## Gateway-lock
|
|
387
|
+
|
|
388
|
+
Every call goes to the CloakAPI gateway (`cloakapi.io` / `*.cloakapi.io` over
|
|
389
|
+
https) or to a loopback address (for the local proxy, development and tests).
|
|
390
|
+
Any other base URL is rejected in the constructor.
|
|
391
|
+
|
|
392
|
+
## License
|
|
393
|
+
|
|
394
|
+
Apache-2.0 © 2024-2026 Klokk Nettablering. See LICENSE and NOTICE.
|
|
395
|
+
|
|
396
|
+
## Offline receipt verification status
|
|
397
|
+
|
|
398
|
+
`Receipts.verify_receipt` checks the envelope signature with the public key you
|
|
399
|
+
pass. If `claims.countersignature` is present, `VerifyResult#kind` is
|
|
400
|
+
`unverified-witness`, `witness_checked` is false, and `reason` links to the
|
|
401
|
+
explanation. This method does not check the independent gateway signature or
|
|
402
|
+
its receipt-hash binding. Use the full-entry and JWKS checks described in
|
|
403
|
+
[receipt verification docs](https://docs.cloakapi.io/receipts/verify/) for that
|
|
404
|
+
result.
|
|
405
|
+
|
|
406
|
+
**Compatibility:** this case previously returned `gateway-only-pass`; update
|
|
407
|
+
callers matching that string to `unverified-witness`.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
notice-profile: sdk
|
|
4
|
+
|
|
5
|
+
This file lists third-party software and data shipped with this package.
|
|
6
|
+
It replaces the monorepo-wide pnpm table, which is not the contents of this tarball.
|
|
7
|
+
|
|
8
|
+
## Data
|
|
9
|
+
|
|
10
|
+
GeoNames (https://www.geonames.org/), CC BY 4.0
|
|
11
|
+
(https://creativecommons.org/licenses/by/4.0/).
|
|
12
|
+
Modified: filtered, endonym-gated and compacted.
|
|
13
|
+
The license text is licenses/CC-BY-4.0.txt.
|
|
14
|
+
|
|
15
|
+
Faker (@faker-js/faker locale datasets), MIT.
|
|
16
|
+
The name gazetteer records that source. The MIT text is licenses/MIT-Faker.txt.
|
|
17
|
+
|
|
18
|
+
Wikidata labels used as gazetteer input: CC0.
|
|
19
|
+
|
|
20
|
+
US Census place names used as gazetteer input: public domain.
|
|
21
|
+
|
|
22
|
+
Models loaded at runtime are not part of this package and have their own terms; the application that loads a model ships that model's notice.
|
data/TRADEMARKS.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# CloakAPI trademark policy
|
|
2
|
+
|
|
3
|
+
"CloakAPI", the CloakAPI logo and "Verified by CloakAPI" are trademarks of
|
|
4
|
+
Klokk Nettablering, Norway. The Apache License 2.0 does not license them
|
|
5
|
+
(section 6).
|
|
6
|
+
|
|
7
|
+
You may:
|
|
8
|
+
- say truthfully that your software uses, or works with, the CloakAPI SDK;
|
|
9
|
+
- keep and reproduce the NOTICE file, as the license requires.
|
|
10
|
+
|
|
11
|
+
You may not:
|
|
12
|
+
- call a modified version "CloakAPI" or "CloakAPI SDK", or publish it under
|
|
13
|
+
the @cloakapi scope or a name that suggests it comes from us;
|
|
14
|
+
- show the "Verified by CloakAPI" badge except as described at
|
|
15
|
+
https://docs.cloakapi.io (Verified by CloakAPI);
|
|
16
|
+
- suggest that we endorse, support or certify a modified version.
|
|
17
|
+
|
|
18
|
+
If you change the SDK, give your version a different name and say that it
|
|
19
|
+
is not an official CloakAPI release. Questions: trust@cloakapi.io
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# A stand-in for the CloakAPI gateway, for trying the SDK without a key.
|
|
4
|
+
#
|
|
5
|
+
# ruby examples/fake_gateway.rb [port] (default 8787, loopback only)
|
|
6
|
+
#
|
|
7
|
+
# It answers the two calls a send makes:
|
|
8
|
+
# POST /api/v1/pretokenised/mac -> {"mac": "<HMAC-SHA256 of the body, demo key>"}
|
|
9
|
+
# POST /api/v1/messages -> a reply that repeats the user text it received
|
|
10
|
+
# POST /api/v1/chat/completions -> the same in the chat format
|
|
11
|
+
# and, when FAKE_GATEWAY_LOG names a file, appends one JSON line per request
|
|
12
|
+
# (method, path, headers without the key, body) so you can see exactly what
|
|
13
|
+
# left the SDK. It checks nothing and is not the gateway: it only shows the
|
|
14
|
+
# request shape.
|
|
15
|
+
|
|
16
|
+
require "json"
|
|
17
|
+
require "openssl"
|
|
18
|
+
require "socket"
|
|
19
|
+
|
|
20
|
+
port = (ARGV[0] || ENV["FAKE_GATEWAY_PORT"] || 8787).to_i
|
|
21
|
+
log_path = ENV["FAKE_GATEWAY_LOG"]
|
|
22
|
+
server = TCPServer.new("127.0.0.1", port)
|
|
23
|
+
warn "stand-in gateway listening on http://127.0.0.1:#{port}"
|
|
24
|
+
|
|
25
|
+
def user_text(body)
|
|
26
|
+
parsed = JSON.parse(body)
|
|
27
|
+
message = Array(parsed["messages"]).reverse.find { |m| m.is_a?(Hash) && m["role"] == "user" }
|
|
28
|
+
content = message && message["content"]
|
|
29
|
+
content.is_a?(Array) ? content.map { |part| part.is_a?(Hash) ? part["text"].to_s : "" }.join(" ") : content.to_s
|
|
30
|
+
rescue JSON::ParserError
|
|
31
|
+
""
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
loop do
|
|
35
|
+
socket = server.accept
|
|
36
|
+
begin
|
|
37
|
+
request_line = socket.gets.to_s
|
|
38
|
+
method, path, = request_line.split(" ")
|
|
39
|
+
headers = {}
|
|
40
|
+
while (line = socket.gets) && line != "\r\n"
|
|
41
|
+
name, value = line.split(":", 2)
|
|
42
|
+
headers[name.strip] = value.to_s.strip
|
|
43
|
+
end
|
|
44
|
+
length = headers.find { |name, _| name.casecmp?("content-length") }&.last.to_i
|
|
45
|
+
body = length.positive? ? socket.read(length).to_s.force_encoding(Encoding::UTF_8) : ""
|
|
46
|
+
|
|
47
|
+
if log_path
|
|
48
|
+
shown = headers.reject { |name, _| name.casecmp?("authorization") }
|
|
49
|
+
entry = { "method" => method, "path" => path, "headers" => shown,
|
|
50
|
+
"auth_present" => headers.any? { |name, _| name.casecmp?("authorization") }, "body" => body }
|
|
51
|
+
File.open(log_path, "a") { |file| file.puts(JSON.generate(entry)) }
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
status = 200
|
|
55
|
+
answer =
|
|
56
|
+
case [method, path]
|
|
57
|
+
when ["POST", "/api/v1/pretokenised/mac"]
|
|
58
|
+
{ "mac" => OpenSSL::HMAC.hexdigest("SHA256", "stand-in-gateway", body) }
|
|
59
|
+
when ["POST", "/api/v1/messages"]
|
|
60
|
+
{ "id" => "msg_standin", "type" => "message", "role" => "assistant",
|
|
61
|
+
"content" => [{ "type" => "text", "text" => "You wrote: #{user_text(body)}" }] }
|
|
62
|
+
when ["POST", "/api/v1/chat/completions"]
|
|
63
|
+
{ "id" => "chat_standin", "object" => "chat.completion",
|
|
64
|
+
"choices" => [{ "index" => 0, "finish_reason" => "stop",
|
|
65
|
+
"message" => { "role" => "assistant", "content" => "You wrote: #{user_text(body)}" } }] }
|
|
66
|
+
else
|
|
67
|
+
status = 404
|
|
68
|
+
{ "error" => { "code" => "not_found", "type" => "invalid_request_error" } }
|
|
69
|
+
end
|
|
70
|
+
payload = JSON.generate(answer)
|
|
71
|
+
socket.write("HTTP/1.1 #{status} #{status == 200 ? 'OK' : 'Not Found'}\r\nContent-Type: application/json\r\n" \
|
|
72
|
+
"Content-Length: #{payload.bytesize}\r\nConnection: close\r\n\r\n#{payload}")
|
|
73
|
+
rescue StandardError => e
|
|
74
|
+
warn "stand-in gateway: #{e.class}"
|
|
75
|
+
ensure
|
|
76
|
+
socket.close
|
|
77
|
+
end
|
|
78
|
+
end
|
data/examples/hello.rb
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# CloakAPI hello world.
|
|
4
|
+
#
|
|
5
|
+
# CLOAKAPI_API_KEY=... ruby examples/hello.rb
|
|
6
|
+
#
|
|
7
|
+
# Without a key you can still run it against the stand-in gateway:
|
|
8
|
+
#
|
|
9
|
+
# ruby examples/fake_gateway.rb 8787 &
|
|
10
|
+
# CLOAKAPI_API_KEY=test CLOAKAPI_BASE_URL=http://127.0.0.1:8787 ruby examples/hello.rb
|
|
11
|
+
#
|
|
12
|
+
# Set CLOAKAPI_APPROVE=yes or =no to answer the question without typing.
|
|
13
|
+
|
|
14
|
+
begin
|
|
15
|
+
require "cloakapi"
|
|
16
|
+
rescue LoadError
|
|
17
|
+
$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
|
|
18
|
+
require "cloakapi"
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
key = ENV.fetch("CLOAKAPI_API_KEY", "")
|
|
22
|
+
if key.empty?
|
|
23
|
+
warn "Set CLOAKAPI_API_KEY to your CloakAPI key (https://app.cloakapi.io), or use the stand-in gateway " \
|
|
24
|
+
"described at the top of this file."
|
|
25
|
+
exit 1
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# The review callback: it is handed the exact text that would be sent and the
|
|
29
|
+
# detection state. Nothing is sent unless it returns true.
|
|
30
|
+
review = lambda do |text, info|
|
|
31
|
+
puts "This is what will be sent:"
|
|
32
|
+
puts text
|
|
33
|
+
puts "Detection: #{info.coverage} (#{info.state})"
|
|
34
|
+
info.warnings.each { |warning| puts "Note: #{warning.message}" }
|
|
35
|
+
answer = ENV["CLOAKAPI_APPROVE"]
|
|
36
|
+
if answer.nil?
|
|
37
|
+
print "Send it? [y/N] "
|
|
38
|
+
answer = $stdin.gets.to_s
|
|
39
|
+
end
|
|
40
|
+
answer.strip.downcase.start_with?("y")
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
client = CloakAPI::Client.new(key, base_url: ENV["CLOAKAPI_BASE_URL"], review: review, max_retries: 0)
|
|
44
|
+
|
|
45
|
+
begin
|
|
46
|
+
reply = client.messages.create(
|
|
47
|
+
model: ENV.fetch("CLOAKAPI_MODEL", "claude-sonnet-4-6"),
|
|
48
|
+
max_tokens: 200,
|
|
49
|
+
messages: [{ role: "user", content: "Write a one-line reply to jane.roe@example.com confirming Tuesday." }]
|
|
50
|
+
)
|
|
51
|
+
puts "Reply (original values restored on this machine):"
|
|
52
|
+
puts reply.dig("content", 0, "text")
|
|
53
|
+
rescue CloakAPI::ReviewRequiredError
|
|
54
|
+
puts "Not sent."
|
|
55
|
+
rescue CloakAPI::ApiError => e
|
|
56
|
+
warn "The gateway answered HTTP #{e.status_code}#{e.code.empty? ? '' : " (#{e.code})"}."
|
|
57
|
+
if e.status_code == 428
|
|
58
|
+
warn "The gateway asks for the on-device engine for this request. See \"The native engine and its pin\" in the README."
|
|
59
|
+
end
|
|
60
|
+
exit 2
|
|
61
|
+
rescue CloakAPI::PretokenisedMacError
|
|
62
|
+
warn "Could not reach the gateway, or it refused the key. Nothing was sent to a model."
|
|
63
|
+
exit 2
|
|
64
|
+
end
|