cloakapi 1.4.1-x86_64-linux
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +160 -0
- data/LICENSE +202 -0
- data/NOTICE +18 -0
- data/README.md +407 -0
- data/THIRD-PARTY-NOTICES.md +22 -0
- data/TRADEMARKS.md +19 -0
- data/examples/fake_gateway.rb +78 -0
- data/examples/hello.rb +64 -0
- data/lib/cloakapi/_lib/linux-x86_64/libcloak_engine.so +0 -0
- data/lib/cloakapi/client.rb +1272 -0
- data/lib/cloakapi/degraded.rb +77 -0
- data/lib/cloakapi/disclosure.rb +252 -0
- data/lib/cloakapi/engine.rb +702 -0
- data/lib/cloakapi/errors.rb +65 -0
- data/lib/cloakapi/pii/bundled_rules.rb +670 -0
- data/lib/cloakapi/pii/card_spans.rb +300 -0
- data/lib/cloakapi/pii/detector.rb +1925 -0
- data/lib/cloakapi/pii/patterns.json +2238 -0
- data/lib/cloakapi/pii/pii_match.rb +7 -0
- data/lib/cloakapi/pii/pii_type.rb +7 -0
- data/lib/cloakapi/pii/ruleset.rb +65 -0
- data/lib/cloakapi/pii/tokenizer.rb +411 -0
- data/lib/cloakapi/posture.rb +82 -0
- data/lib/cloakapi/receipts.rb +406 -0
- data/lib/cloakapi/resources/chat.rb +82 -0
- data/lib/cloakapi/resources/messages.rb +90 -0
- data/lib/cloakapi/resources/models.rb +25 -0
- data/lib/cloakapi/resources/receipts.rb +162 -0
- data/lib/cloakapi/resources/reconstruct.rb +120 -0
- data/lib/cloakapi/resources/request_strings.rb +485 -0
- data/lib/cloakapi/resources/reviewable.rb +163 -0
- data/lib/cloakapi/resources/tokens.rb +28 -0
- data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
- data/lib/cloakapi/routing.rb +500 -0
- data/lib/cloakapi/streaming.rb +196 -0
- data/lib/cloakapi/surrogate_mode.rb +233 -0
- data/lib/cloakapi/version.rb +15 -0
- data/lib/cloakapi/warnings.rb +137 -0
- data/lib/cloakapi.rb +37 -0
- data/licenses/Apache-2.0.txt +202 -0
- data/licenses/CC-BY-4.0.txt +104 -0
- data/licenses/MIT-Faker.txt +21 -0
- data/licenses/MIT.txt +21 -0
- metadata +150 -0
|
@@ -0,0 +1,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
|