cloakapi 1.4.1-x86_64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +160 -0
  3. data/LICENSE +202 -0
  4. data/NOTICE +18 -0
  5. data/README.md +407 -0
  6. data/THIRD-PARTY-NOTICES.md +22 -0
  7. data/TRADEMARKS.md +19 -0
  8. data/examples/fake_gateway.rb +78 -0
  9. data/examples/hello.rb +64 -0
  10. data/lib/cloakapi/_lib/linux-x86_64/libcloak_engine.so +0 -0
  11. data/lib/cloakapi/client.rb +1272 -0
  12. data/lib/cloakapi/degraded.rb +77 -0
  13. data/lib/cloakapi/disclosure.rb +252 -0
  14. data/lib/cloakapi/engine.rb +702 -0
  15. data/lib/cloakapi/errors.rb +65 -0
  16. data/lib/cloakapi/pii/bundled_rules.rb +670 -0
  17. data/lib/cloakapi/pii/card_spans.rb +300 -0
  18. data/lib/cloakapi/pii/detector.rb +1925 -0
  19. data/lib/cloakapi/pii/patterns.json +2238 -0
  20. data/lib/cloakapi/pii/pii_match.rb +7 -0
  21. data/lib/cloakapi/pii/pii_type.rb +7 -0
  22. data/lib/cloakapi/pii/ruleset.rb +65 -0
  23. data/lib/cloakapi/pii/tokenizer.rb +411 -0
  24. data/lib/cloakapi/posture.rb +82 -0
  25. data/lib/cloakapi/receipts.rb +406 -0
  26. data/lib/cloakapi/resources/chat.rb +82 -0
  27. data/lib/cloakapi/resources/messages.rb +90 -0
  28. data/lib/cloakapi/resources/models.rb +25 -0
  29. data/lib/cloakapi/resources/receipts.rb +162 -0
  30. data/lib/cloakapi/resources/reconstruct.rb +120 -0
  31. data/lib/cloakapi/resources/request_strings.rb +485 -0
  32. data/lib/cloakapi/resources/reviewable.rb +163 -0
  33. data/lib/cloakapi/resources/tokens.rb +28 -0
  34. data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
  35. data/lib/cloakapi/routing.rb +500 -0
  36. data/lib/cloakapi/streaming.rb +196 -0
  37. data/lib/cloakapi/surrogate_mode.rb +233 -0
  38. data/lib/cloakapi/version.rb +15 -0
  39. data/lib/cloakapi/warnings.rb +137 -0
  40. data/lib/cloakapi.rb +37 -0
  41. data/licenses/Apache-2.0.txt +202 -0
  42. data/licenses/CC-BY-4.0.txt +104 -0
  43. data/licenses/MIT-Faker.txt +21 -0
  44. data/licenses/MIT.txt +21 -0
  45. metadata +150 -0
@@ -0,0 +1,406 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "openssl"
4
+ require "digest"
5
+ require "json"
6
+ require "securerandom"
7
+
8
+ module CloakAPI
9
+ # OpenReceipt device-receipt SIGN + offline VERIFY (pure stdlib crypto).
10
+ #
11
+ # ECDSA P-256 / SHA-256, RFC-8785 (JCS) canonicalisation, raw +r||s+
12
+ # signatures base64url-encoded. No native build step, no extra gem — uses only
13
+ # the +openssl+ stdlib. This is the Ruby port of the TypeScript reference
14
+ # (+src/browser/sign-receipt.ts+ / +src/receipts.ts+) and the pure-Python
15
+ # verifier (+cloakapi/receipts.py+):
16
+ #
17
+ # * {sign_device_receipt} mints a self-contained, content-free v3 device
18
+ # receipt ON-DEVICE (hashes + counts + category labels only — never text).
19
+ # * {verify_receipt} proves a receipt's signature against a pinned public key,
20
+ # fully OFFLINE (no gateway).
21
+ # * {verify_chain_links} walks an ordered receipt-chain export for structural
22
+ # integrity, also offline.
23
+ #
24
+ # The embedded public key makes each minted receipt tamper-evident and
25
+ # self-verifiable (the key is inside the signed bytes).
26
+ module Receipts
27
+ class StrictJsonObject < Hash
28
+ def []=(key, value)
29
+ raise JSON::ParserError, "duplicate JSON object key" if key?(key)
30
+
31
+ super
32
+ end
33
+ end
34
+ private_constant :StrictJsonObject
35
+
36
+ # A signing/verification failure that should be treated as "no proof".
37
+ class DeviceReceiptError < StandardError; end
38
+
39
+ RECEIPT_TYP = "cloak-device-receipt"
40
+
41
+ # ── JCS canonicalisation (RFC 8785) ──────────────────────────────────────
42
+
43
+ # Encode a Ruby JSON value to RFC-8785 canonical UTF-8 bytes. Mirrors the
44
+ # Python reference +canonicalise+ and the TS +canonicalise+ byte-for-byte:
45
+ # object keys sorted lexicographically (by UTF-16 code unit, which for the
46
+ # ASCII keys used here equals byte order), no insignificant whitespace,
47
+ # minimal string escaping, integers as bare digits.
48
+ def self.canonicalise(value)
49
+ jcs_str(value).encode("UTF-8").b
50
+ end
51
+
52
+ # SHA-256 hex of the JCS-canonical form of +value+.
53
+ def self.canonical_sha256(value)
54
+ Digest::SHA256.hexdigest(canonicalise(value))
55
+ end
56
+
57
+ def self.jcs_str(value)
58
+ case value
59
+ when nil then "null"
60
+ when true then "true"
61
+ when false then "false"
62
+ when Integer then value.to_s
63
+ when Float then jcs_number(value)
64
+ when String then jcs_string(value)
65
+ when Symbol then jcs_string(value.to_s)
66
+ when Array then "[" + value.map { |v| jcs_str(v) }.join(",") + "]"
67
+ when Hash
68
+ pairs = value.map { |k, v| [k.to_s, v] }.sort_by { |k, _| k.encode("UTF-16BE").unpack("n*") }
69
+ "{" + pairs.map { |k, v| jcs_string(k) + ":" + jcs_str(v) }.join(",") + "}"
70
+ else
71
+ raise DeviceReceiptError, "cannot canonicalise #{value.class}"
72
+ end
73
+ end
74
+ private_class_method :jcs_str
75
+
76
+ # RFC-8785 §3.2.2.2 string escaping.
77
+ def self.jcs_string(str)
78
+ out = +'"'
79
+ str.each_char do |ch|
80
+ cp = ch.ord
81
+ case cp
82
+ when 0x22 then out << '\\"'
83
+ when 0x5C then out << "\\\\"
84
+ when 0x08 then out << "\\b"
85
+ when 0x09 then out << "\\t"
86
+ when 0x0A then out << "\\n"
87
+ when 0x0C then out << "\\f"
88
+ when 0x0D then out << "\\r"
89
+ else
90
+ if cp < 0x20
91
+ out << format("\\u%04x", cp)
92
+ else
93
+ out << ch
94
+ end
95
+ end
96
+ end
97
+ out << '"'
98
+ out
99
+ end
100
+ private_class_method :jcs_string
101
+
102
+ def self.jcs_number(num)
103
+ # Float::NAN.to_s is "NaN" and Float::INFINITY.to_s is "Infinity".
104
+ # Those tokens are not JSON; refuse them instead of canonicalising.
105
+ raise DeviceReceiptError, "non-finite number" unless num.finite?
106
+
107
+ return num.to_i.to_s if num == num.to_i
108
+
109
+ num.to_s
110
+ end
111
+ private_class_method :jcs_number
112
+
113
+ # ── base64url ─────────────────────────────────────────────────────────────
114
+
115
+ def self.b64url_encode(bytes)
116
+ # RFC 4648 section 5, no padding (what Base64.urlsafe_encode64(bytes, padding: false) returns).
117
+ [bytes].pack("m0").tr("+/", "-_").delete("=")
118
+ end
119
+
120
+ def self.b64url_decode(str)
121
+ s = str.to_s
122
+ return "".b unless /\A[A-Za-z0-9_-]*\z/.match?(s) && (s.length % 4) != 1
123
+
124
+ s = s.tr("-_", "+/")
125
+ s += "=" * ((4 - (s.length % 4)) % 4)
126
+ s.unpack1("m0") # strict RFC 4648 decoding; raises ArgumentError on anything else
127
+ rescue ArgumentError
128
+ "".b
129
+ end
130
+
131
+ # ── public-key loading (uncompressed-point hex → OpenSSL::PKey::EC) ────────
132
+
133
+ P256_GROUP = "prime256v1"
134
+
135
+ # Build a verify-capable EC public key from an uncompressed-point hex string
136
+ # (0x04||X||Y, 130 hex chars). Ruby 3.x EC keys are immutable, so we assemble
137
+ # a SubjectPublicKeyInfo DER and load it via OpenSSL::PKey.read.
138
+ def self.load_public_key_hex(hex)
139
+ raw = [hex.to_s.strip].pack("H*")
140
+ raise DeviceReceiptError, "public key must be an uncompressed P-256 point (65 bytes)" \
141
+ if raw.bytesize != 65 || raw.getbyte(0) != 0x04
142
+
143
+ alg = OpenSSL::ASN1::Sequence([
144
+ OpenSSL::ASN1::ObjectId("id-ecPublicKey"),
145
+ OpenSSL::ASN1::ObjectId("prime256v1"),
146
+ ])
147
+ spki = OpenSSL::ASN1::Sequence([
148
+ alg,
149
+ OpenSSL::ASN1::BitString(raw),
150
+ ])
151
+ OpenSSL::PKey.read(spki.to_der)
152
+ end
153
+
154
+ # ── sign / verify signature-format helpers ────────────────────────────────
155
+
156
+ # Convert an ECDSA DER signature to raw r||s (64 bytes, each left-padded to 32).
157
+ def self.der_to_raw(der)
158
+ asn1 = OpenSSL::ASN1.decode(der)
159
+ r = asn1.value[0].value.to_s(2)
160
+ s = asn1.value[1].value.to_s(2)
161
+ pad(r) + pad(s)
162
+ end
163
+ private_class_method :der_to_raw
164
+
165
+ def self.pad(bytes)
166
+ bytes = bytes.b
167
+ raise DeviceReceiptError, "signature component too large" if bytes.bytesize > 32
168
+
169
+ ("\x00".b * (32 - bytes.bytesize)) + bytes
170
+ end
171
+ private_class_method :pad
172
+
173
+ # Convert raw r||s (64 bytes) to an ECDSA DER signature.
174
+ def self.raw_to_der(raw)
175
+ raise DeviceReceiptError, "invalid sig length #{raw.bytesize}" if raw.bytesize != 64
176
+
177
+ r = OpenSSL::BN.new(raw[0, 32].unpack1("H*"), 16)
178
+ s = OpenSSL::BN.new(raw[32, 32].unpack1("H*"), 16)
179
+ OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(r), OpenSSL::ASN1::Integer(s)]).to_der
180
+ end
181
+ private_class_method :raw_to_der
182
+
183
+ # ── key generation ────────────────────────────────────────────────────────
184
+
185
+ # Generate a fresh ECDSA P-256 key pair for device-receipt signing. Returns
186
+ # the OpenSSL::PKey::EC (holds both private + public). Exposed so a caller can
187
+ # persist a stable device identity; by default {sign_device_receipt} mints an
188
+ # ephemeral pair per receipt.
189
+ def self.generate_device_key_pair
190
+ OpenSSL::PKey::EC.generate(P256_GROUP)
191
+ end
192
+
193
+ # Uncompressed-point hex (0x04||X||Y) of a key's public point.
194
+ def self.public_key_hex(key)
195
+ key.public_key.to_octet_string(:uncompressed).unpack1("H*")
196
+ end
197
+
198
+ # ── signing (C8) ──────────────────────────────────────────────────────────
199
+
200
+ # Sign a content-free device receipt ON-DEVICE (ECDSA P-256 + JCS). Returns a
201
+ # self-contained v3 receipt Hash that {verify_receipt} validates offline via
202
+ # the embedded public key. FAIL-CLOSED: raises {DeviceReceiptError} if signing
203
+ # fails — the caller must treat a raise as "no receipt, do not claim proof".
204
+ #
205
+ # @param entity_count [Integer] total entities tokenised on-device
206
+ # @param file_entity_count [Integer] how many came from an attached file/image
207
+ # @param categories [Array<String>] content-free PII category labels
208
+ # @param output_hash [String, nil] sha-256 hex of the tokenised output egressed
209
+ # @param engine_version [String, nil] X-Cloak-Engine-Version
210
+ # @param engine_hash [String, nil] X-Cloak-Engine-Hash
211
+ # @param extra_claims [Hash] extra content-free claims folded into the attestation
212
+ # @param key [OpenSSL::PKey::EC, nil] reuse a key pair (else ephemeral)
213
+ # @param jti [String, nil] override the receipt id (default random UUID)
214
+ # @param iat [Integer, nil] override issued-at unix seconds (default now)
215
+ def self.sign_device_receipt(entity_count: 0, file_entity_count: 0, categories: nil,
216
+ output_hash: nil, engine_version: nil, engine_hash: nil,
217
+ extra_claims: nil, key: nil, jti: nil, iat: nil)
218
+ signing_key = key || generate_device_key_pair
219
+
220
+ # CANONICAL v3-attestation (matches @cloakapi/conformance + gateway
221
+ # countersign + cloakup producers): canonical engine field names
222
+ # (engine_ruleset_version / engine_binary_hash) + the Level-1 fields so the
223
+ # conformance client-side-tokenisation check PASSes out of the box.
224
+ # genuine_engine is only asserted alongside a real binary hash — a fallback
225
+ # (regex) run omits the hash so engine-genuine stays UNKNOWN, never FALSE.
226
+ attestation = {
227
+ "attester_public_key" => public_key_hex(signing_key),
228
+ "entity_count" => [0, entity_count.to_i].max,
229
+ "file_entity_count" => [0, file_entity_count.to_i].max,
230
+ "detector_categories" => Array(categories).map(&:to_s),
231
+ "output_sha256" => output_hash,
232
+ "no_raw_pii_egress" => true,
233
+ "tokenised_body_hash" => output_hash,
234
+ "privacy_tier" => "local-only",
235
+ "engine_ruleset_version" => engine_version,
236
+ }
237
+ if engine_hash && !engine_hash.to_s.empty?
238
+ attestation["engine_binary_hash"] = engine_hash
239
+ attestation["genuine_engine"] = true
240
+ end
241
+ reserved = %w[
242
+ attester_public_key entity_count file_entity_count detector_categories
243
+ output_sha256 tokenised_body_hash privacy_tier engine_ruleset_version
244
+ engine_binary_hash genuine_engine no_raw_pii_egress attestation_version
245
+ file_build file_egress
246
+ ]
247
+ (extra_claims || {}).each do |k, v|
248
+ key = k.to_s
249
+ attestation[key] = v unless reserved.include?(key)
250
+ end
251
+
252
+ unsigned = {
253
+ "jti" => jti || SecureRandom.uuid,
254
+ "iat" => (iat || Time.now.to_i).to_i,
255
+ "typ" => RECEIPT_TYP,
256
+ "claims" => { "v3-attestation" => attestation },
257
+ }
258
+
259
+ der = signing_key.sign(OpenSSL::Digest.new("SHA256"), canonicalise(unsigned))
260
+ unsigned.merge("sig" => b64url_encode(der_to_raw(der)))
261
+ rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::ECError => e
262
+ raise DeviceReceiptError, "receipt signing failed: #{e.message}"
263
+ end
264
+
265
+ # Outcome of an offline receipt verification.
266
+ # ok — signature valid?
267
+ # kind — 'pass' | 'unverified-witness' | 'desktop-only-pass' | 'fail'
268
+ # reason — human-readable reason on failure ("" on success)
269
+ WITNESS_NOT_CHECKED_REASON = "Signature checked; independent witness NOT checked. See https://docs.cloakapi.io/receipts/verify/#what-a-receipt-check-proves-and-what-it-does-not.".freeze
270
+
271
+ # SHA-256 of the empty string. Producers write it when they commit no token binding.
272
+ EMPTY_TOKEN_BINDING_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855".freeze
273
+
274
+ # An empty binding is a valid signature and is never a token-binding proof.
275
+ # Same wording as the TypeScript verifier.
276
+ NO_TOKEN_BINDING_NOTE = "receipt.claims.v3-attestation.token_binding_hmac: empty, no token binding committed".freeze
277
+
278
+ VerifyResult = Data.define(:ok, :kind, :reason, :witness_checked) do
279
+ def ok? = ok
280
+ end
281
+
282
+ # ── verification (C9) ─────────────────────────────────────────────────────
283
+
284
+ # Verify a signed receipt against a hex-encoded uncompressed P-256 public key,
285
+ # fully OFFLINE. Signature = raw r||s (64 bytes) base64url; signed bytes =
286
+ # JCS-canonical envelope with the +sig+ field removed. Mirrors the Python /
287
+ # TS verifiers. Never raises on a bad signature — returns a failing result.
288
+ #
289
+ # @param receipt [Hash] the receipt envelope (with "sig")
290
+ # @param public_key_hex [String] uncompressed-point hex of the pinned key
291
+ # @return [VerifyResult]
292
+ def self.verify_receipt(receipt, public_key_hex)
293
+ env = normalise(receipt)
294
+ sig = env["sig"].to_s
295
+ sig = env["signature"].to_s if sig.empty?
296
+ raw = b64url_decode(sig)
297
+ return VerifyResult.new(ok: false, kind: "fail", reason: "invalid sig length #{raw.bytesize}", witness_checked: false) \
298
+ if raw.bytesize != 64
299
+
300
+ without_sig = env.reject { |k, _| k == "sig" || k == "signature" }
301
+ canonical = canonicalise(without_sig)
302
+
303
+ begin
304
+ pub = load_public_key_hex(public_key_hex)
305
+ valid = pub.verify(OpenSSL::Digest.new("SHA256"), raw_to_der(raw), canonical)
306
+ rescue DeviceReceiptError, OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error => e
307
+ return VerifyResult.new(ok: false, kind: "fail", reason: e.message, witness_checked: false)
308
+ end
309
+
310
+ return VerifyResult.new(ok: false, kind: "fail", reason: "signature mismatch", witness_checked: false) unless valid
311
+
312
+ claims = env["claims"].is_a?(Hash) ? env["claims"] : {}
313
+ has_desktop = claims.key?("egress_attestation")
314
+ gateway = claims["countersignature"]
315
+ has_gateway = gateway.is_a?(Hash) && !gateway.empty?
316
+
317
+ kind = if has_gateway
318
+ "unverified-witness"
319
+ elsif has_desktop
320
+ "desktop-only-pass"
321
+ else
322
+ "pass"
323
+ end
324
+ reason = has_gateway ? WITNESS_NOT_CHECKED_REASON : ""
325
+ note = no_token_binding_note(claims)
326
+ reason = note if reason.empty? && note
327
+ reason = "#{reason} #{note}" if !reason.empty? && note && !reason.include?(note)
328
+ VerifyResult.new(ok: true, kind: kind, reason: reason, witness_checked: false)
329
+ end
330
+
331
+ # Empty string or the SHA-256 of the empty string. A missing field is not
332
+ # that case. A different non-empty value is not credited as a binding proof.
333
+ def self.no_token_binding_note(claims)
334
+ attestation = claims["v3-attestation"]
335
+ return nil unless attestation.is_a?(Hash)
336
+ binding = attestation["token_binding_hmac"]
337
+ return nil unless binding.is_a?(String)
338
+ return NO_TOKEN_BINDING_NOTE if binding.empty? || binding.downcase == EMPTY_TOKEN_BINDING_SHA256
339
+
340
+ nil
341
+ end
342
+ private_class_method :no_token_binding_note
343
+
344
+ # SHA-256 hex of the receipt's full canonical form (INCLUDING sig).
345
+ def self.receipt_hash(receipt)
346
+ canonical_sha256(normalise(receipt))
347
+ end
348
+
349
+ # Walk an ordered receipt-chain export and verify structural integrity WITHOUT
350
+ # any network call:
351
+ # * entries[i].prev_hash == entries[i-1].canonical_sha256 for i > 0
352
+ # * entries[i].seq == i (dense, monotonic from 0)
353
+ # Returns [chain_ok, entries_verified, break_index] (break_index nil if intact).
354
+ def self.verify_chain_links(entries)
355
+ return [false, 0, 0] unless entries.is_a?(Array)
356
+
357
+ prev_hash = nil
358
+ entries.each_with_index do |e, i|
359
+ # normalise raises DeviceReceiptError for nil / non-objects and
360
+ # JSON::ParserError for a string that is not JSON. Either used to
361
+ # abort the walk; a corrupt export entry is a break at that index.
362
+ begin
363
+ e = normalise(e)
364
+ rescue DeviceReceiptError, JSON::ParserError
365
+ return [false, i, i]
366
+ end
367
+ seq = e["seq"]
368
+ return [false, i, i] unless seq.is_a?(Integer) && seq == i
369
+ hash = e["canonical_sha256"]
370
+ return [false, i, i] unless hash.is_a?(String) && !hash.empty?
371
+ return [false, i, i] if i.positive? && e["prev_hash"] != prev_hash
372
+
373
+ prev_hash = hash
374
+ end
375
+ [true, entries.length, nil]
376
+ end
377
+
378
+ # Accept a Hash (string OR symbol keys) or a JSON string; return string-keyed.
379
+ def self.normalise(receipt)
380
+ obj = if receipt.is_a?(String)
381
+ # A receipt with the same member twice is refused. Older json
382
+ # versions build objects through []= (StrictJsonObject raises);
383
+ # newer ones do not call it and take allow_duplicate_key instead.
384
+ # Each ignores the other mechanism, so both are given.
385
+ JSON.parse(receipt, object_class: StrictJsonObject, allow_nan: false, allow_duplicate_key: false)
386
+ else
387
+ receipt
388
+ end
389
+ raise DeviceReceiptError, "receipt must be a Hash or JSON object" unless obj.is_a?(Hash)
390
+
391
+ deep_stringify(obj)
392
+ rescue JSON::ParserError => e
393
+ raise DeviceReceiptError, "invalid receipt JSON: #{e.message}"
394
+ end
395
+ private_class_method :normalise
396
+
397
+ def self.deep_stringify(obj)
398
+ case obj
399
+ when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
400
+ when Array then obj.map { |v| deep_stringify(v) }
401
+ else obj
402
+ end
403
+ end
404
+ private_class_method :deep_stringify
405
+ end
406
+ end
@@ -0,0 +1,82 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "request_strings"
4
+ require_relative "reviewable"
5
+
6
+ module CloakAPI
7
+ module Resources
8
+ class Chat
9
+ def initialize(client)
10
+ @completions = Completions.new(client)
11
+ end
12
+
13
+ def completions
14
+ @completions
15
+ end
16
+
17
+ # POST /api/v1/chat/completions (OpenAI format).
18
+ #
19
+ # Message content is tokenised on this device before it is sent, the
20
+ # client asks the gateway for the per-body MAC over the exact outgoing
21
+ # bytes, and the reply's choice messages are restored locally on the way
22
+ # back.
23
+ #
24
+ # +prepare+, +create+, +send_approved+ and +create_stream+ come from
25
+ # {Reviewable}: either prepare, approve and create, or give the client a
26
+ # review callback and call +create(model:, messages:)+ directly.
27
+ #
28
+ # end_user (ADR-0015): OPTIONAL opaque pseudonymous end-user id. Pass it
29
+ # to prepare so X-Cloak-End-User is included in the reviewed request
30
+ # headers; it is never sent in the body. Pass your OWN opaque token.
31
+ # +prepare(stream: true)+ creates the streaming preview; after approval
32
+ # +create_stream+ yields SSE chunks with delta content restored locally.
33
+ # +seed_hex+ (C21b) threads a continuity seed to the engine.
34
+ class Completions
35
+ include Reviewable
36
+
37
+ def initialize(client)
38
+ @client = client
39
+ end
40
+
41
+ private
42
+
43
+ def relay_path = "/api/v1/chat/completions"
44
+ def stream_format = :openai
45
+
46
+ # Return a copy of +message+ with its string content tokenised on-device.
47
+ # Non-string content is passed through unchanged.
48
+ def tokenise_message(client, message, seed_hex = nil)
49
+ return message unless message.is_a?(Hash)
50
+
51
+ key = message.key?(:content) ? :content : ("content" if message.key?("content"))
52
+ return message if key.nil?
53
+
54
+ content = message[key]
55
+ return message unless content.is_a?(String)
56
+
57
+ copy = message.dup
58
+ copy[key] = client.tokenize_outbound(content, seed_hex: seed_hex)
59
+ copy
60
+ end
61
+
62
+ # De-tokenise the assistant content of every choice in the response.
63
+ def detokenise_response(client, resp, token_map)
64
+ return resp unless resp.is_a?(Hash)
65
+
66
+ choices = resp["choices"]
67
+ return resp unless choices.is_a?(Array)
68
+
69
+ choices.each do |choice|
70
+ next unless choice.is_a?(Hash)
71
+
72
+ msg = choice["message"]
73
+ next unless msg.is_a?(Hash) && msg["content"].is_a?(String)
74
+
75
+ msg["content"] = client.detokenize_text(msg["content"], token_map: token_map)
76
+ end
77
+ resp
78
+ end
79
+ end
80
+ end
81
+ end
82
+ end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "request_strings"
4
+ require_relative "reviewable"
5
+
6
+ module CloakAPI
7
+ module Resources
8
+ # POST /api/v1/messages (Anthropic format).
9
+ #
10
+ # Message content (and any +system+ prompt) is tokenised on this device
11
+ # before it is sent, the client asks the gateway for the per-body MAC over
12
+ # the exact outgoing bytes, and the reply's text blocks are restored locally
13
+ # on the way back.
14
+ #
15
+ # +prepare+, +create+, +send_approved+ and +create_stream+ come from
16
+ # {Reviewable}: either prepare, approve and create, or give the client a
17
+ # review callback and call +create(model:, messages:)+ directly.
18
+ #
19
+ # end_user (ADR-0015): OPTIONAL opaque pseudonymous end-user id. Pass it to
20
+ # prepare so X-Cloak-End-User is included in the reviewed request headers;
21
+ # it is never sent in the body. Pass your OWN opaque token, not real
22
+ # personal data.
23
+ # +prepare(stream: true)+ creates the exact streaming preview; after approval
24
+ # +create_stream+ yields SSE event Hashes with text deltas restored locally.
25
+ # +seed_hex+ (C21b) threads a continuity seed to the engine for cross-session
26
+ # stable stand-ins.
27
+ class Messages
28
+ include Reviewable
29
+
30
+ def initialize(client)
31
+ @client = client
32
+ end
33
+
34
+ private
35
+
36
+ def relay_path = "/api/v1/messages"
37
+ def stream_format = :anthropic
38
+
39
+ # Return a copy of +message+ with its string content tokenised on-device.
40
+ # Non-string content (e.g. structured content blocks) is passed through
41
+ # unchanged, matching the Go SDK's string-content contract.
42
+ def tokenise_message(client, message, seed_hex = nil)
43
+ return message unless message.is_a?(Hash)
44
+
45
+ key = message.key?(:content) ? :content : ("content" if message.key?("content"))
46
+ return message if key.nil?
47
+
48
+ content = message[key]
49
+ return message unless content.is_a?(String)
50
+
51
+ copy = message.dup
52
+ copy[key] = client.tokenize_outbound(content, seed_hex: seed_hex)
53
+ copy
54
+ end
55
+
56
+ # De-tokenise the text of every text content block and the input of every tool call in the
57
+ # response. Thinking is never restored (THINKING-AS-WRITTEN).
58
+ def detokenise_response(client, resp, token_map)
59
+ return resp unless resp.is_a?(Hash)
60
+
61
+ content = resp["content"]
62
+ return resp unless content.is_a?(Array)
63
+
64
+ content.each do |block|
65
+ next unless block.is_a?(Hash)
66
+
67
+ if block["type"] == "text" && block["text"].is_a?(String)
68
+ block["text"] = client.detokenize_text(block["text"], token_map: token_map)
69
+ end
70
+ # A tool call the model or a server tool wrote (tool_use, server_tool_use): its input
71
+ # values may hold stand-ins, and the caller's tool needs the real values. Sent back,
72
+ # they are tokenised again.
73
+ next unless block["input"].is_a?(Hash) || block["input"].is_a?(Array)
74
+
75
+ block["input"] = restore_strings(client, block["input"], token_map)
76
+ end
77
+ resp
78
+ end
79
+
80
+ def restore_strings(client, value, token_map)
81
+ case value
82
+ when String then client.detokenize_text(value, token_map: token_map)
83
+ when Hash then value.transform_values { |child| restore_strings(client, child, token_map) }
84
+ when Array then value.map { |child| restore_strings(client, child, token_map) }
85
+ else value
86
+ end
87
+ end
88
+ end
89
+ end
90
+ end
@@ -0,0 +1,25 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloakAPI
4
+ module Resources
5
+ # Live model discovery (C11) via GET /api/v1/models. Mirrors the TS
6
+ # ModelsAPI / Python ModelsResource.
7
+ class Models
8
+ def initialize(client)
9
+ @client = client
10
+ end
11
+
12
+ # Return the LIVE model catalogue the gateway exposes (OpenAI shape
13
+ # +{"object":"list","data":[...]}+). Returns the +data+ array.
14
+ def list
15
+ data = @client.unsafe_raw_api_get("/api/v1/models")
16
+ data.is_a?(Hash) ? (data["data"] || data) : data
17
+ end
18
+
19
+ # Convenience: find one model by id in the live catalogue, or nil.
20
+ def retrieve(model_id)
21
+ list.find { |m| m.is_a?(Hash) && m["id"] == model_id }
22
+ end
23
+ end
24
+ end
25
+ end