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
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