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
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "uri"
|
|
4
|
+
|
|
5
|
+
require_relative "../receipts"
|
|
6
|
+
|
|
7
|
+
module CloakAPI
|
|
8
|
+
module Resources
|
|
9
|
+
# Receipts resource (C10) — the ADR-0014 verifiable-trust surface. Every
|
|
10
|
+
# method maps to a real gateway endpoint; +verify_offline+ proves a receipt
|
|
11
|
+
# against a pinned key with NO network (pure {CloakAPI::Receipts}). Mirrors
|
|
12
|
+
# the TS ReceiptsAPI / Python ReceiptsResource.
|
|
13
|
+
#
|
|
14
|
+
# verify(receipt) POST /api/v1/receipts/verify
|
|
15
|
+
# get(jti) GET /api/v1/receipts/by-jti/{jti}
|
|
16
|
+
# list(...) GET /api/v1/receipts
|
|
17
|
+
# countersign(payload) POST /api/v1/receipts/countersign
|
|
18
|
+
# chain_export(chain_id) GET /api/v1/receipts/chain/export
|
|
19
|
+
# chain_verify(...) export + LOCAL structural walk (+ optional report)
|
|
20
|
+
# verify_offline(...) fully offline ECDSA/JCS verify (no network)
|
|
21
|
+
class Receipts
|
|
22
|
+
def initialize(client)
|
|
23
|
+
@client = client
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# Verify a receipt via the public gateway endpoint. +receipt+ may be the
|
|
27
|
+
# envelope Hash, a +{jti:}+ lookup, or a base64url envelope String (the
|
|
28
|
+
# X-CloakAPI-Receipt header shape). Returns the gateway +{valid, checks}+.
|
|
29
|
+
def prepare_verify(receipt)
|
|
30
|
+
receipt = decode_receipt_string(receipt) if receipt.is_a?(String)
|
|
31
|
+
validate_content_free_receipt!(receipt)
|
|
32
|
+
body = { "receipt" => receipt }
|
|
33
|
+
@client.send(:prepare_review, "/api/v1/receipts/verify", body)
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def verify(reviewed)
|
|
37
|
+
require_reviewed!(reviewed)
|
|
38
|
+
@client.post_reviewed_api(reviewed, path: "/api/v1/receipts/verify")
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# Fetch a receipt envelope by JTI (public by-jti lookup).
|
|
42
|
+
def get(jti)
|
|
43
|
+
@client.unsafe_raw_api_get("/api/v1/receipts/by-jti/#{URI.encode_www_form_component(jti.to_s)}")
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# The unified, per-user receipt ledger across every surface.
|
|
47
|
+
def list(page: 1, per_page: 20, provider: nil, chain_id: nil, surface: nil)
|
|
48
|
+
page = 1 unless page.is_a?(Integer) && page >= 1
|
|
49
|
+
per_page = 20 unless per_page.is_a?(Integer) && per_page >= 1
|
|
50
|
+
params = { "page" => page, "per_page" => per_page }
|
|
51
|
+
params["provider"] = provider if provider
|
|
52
|
+
params["chain_id"] = chain_id if chain_id
|
|
53
|
+
params["surface"] = surface if surface
|
|
54
|
+
@client.unsafe_raw_api_get("/api/v1/receipts?#{URI.encode_www_form(params)}")
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
# Countersign a client-signed egress attestation (two-party chain). Accepts
|
|
58
|
+
# either the v3 open-receipt envelope shape or the legacy desktop shape.
|
|
59
|
+
def prepare_countersign(payload)
|
|
60
|
+
validate_content_free_receipt!(payload)
|
|
61
|
+
@client.send(:prepare_review, "/api/v1/receipts/countersign", payload)
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
def countersign(reviewed)
|
|
65
|
+
require_reviewed!(reviewed)
|
|
66
|
+
@client.post_reviewed_api(reviewed, path: "/api/v1/receipts/countersign")
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
# Ordered, gateway-signed manifest of the caller's receipt chain.
|
|
70
|
+
def chain_export(chain_id = nil)
|
|
71
|
+
path = "/api/v1/receipts/chain/export"
|
|
72
|
+
path = "#{path}?#{URI.encode_www_form('chain_id' => chain_id)}" if chain_id
|
|
73
|
+
@client.unsafe_raw_api_get(path)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Export the chain, verify its integrity LOCALLY (prev_hash links + dense
|
|
77
|
+
# seq), and optionally report the result back to the gateway. Returns
|
|
78
|
+
# +{ "chain_ok" =>, "entries_verified" =>, "break_index" => }+.
|
|
79
|
+
def chain_verify(chain_id = nil, report: false)
|
|
80
|
+
manifest = chain_export(chain_id)
|
|
81
|
+
entries = manifest.is_a?(Hash) ? (manifest["entries"] || []) : []
|
|
82
|
+
ok, verified, break_index = CloakAPI::Receipts.verify_chain_links(entries)
|
|
83
|
+
raise ArgumentError, "explicit review required: prepare_chain_verify_report, inspect preview, approve it, then pass ReviewedRequest" if report
|
|
84
|
+
{ "chain_ok" => ok, "entries_verified" => verified, "break_index" => break_index }
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
def prepare_chain_verify_report(chain_ok:, entries_verified:)
|
|
88
|
+
@client.send(:prepare_review, "/api/v1/receipt/chain-verify",
|
|
89
|
+
{ "chain_ok" => chain_ok, "entries_verified" => entries_verified })
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
def report_chain_verification(reviewed)
|
|
93
|
+
require_reviewed!(reviewed)
|
|
94
|
+
@client.post_reviewed_api(reviewed, path: "/api/v1/receipt/chain-verify")
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
# Verify a receipt fully offline (no network) against a pinned P-256 public
|
|
98
|
+
# key hex (uncompressed point). Returns a {CloakAPI::Receipts::VerifyResult}.
|
|
99
|
+
def verify_offline(receipt, public_key_hex:)
|
|
100
|
+
CloakAPI::Receipts.verify_receipt(receipt, public_key_hex)
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
private
|
|
104
|
+
|
|
105
|
+
def require_reviewed!(reviewed)
|
|
106
|
+
return if reviewed.is_a?(CloakAPI::Client::ReviewedRequest)
|
|
107
|
+
|
|
108
|
+
raise ArgumentError, "explicit review required: prepare the request, inspect preview, approve it, then pass ReviewedRequest"
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
RECEIPT_FIELDS = %w[jti iat typ sig signature claims egress_attestation countersignature
|
|
112
|
+
v3-attestation attester_public_key entity_count file_entity_count
|
|
113
|
+
detector_categories output_sha256 no_raw_pii_egress tokenised_body_hash
|
|
114
|
+
privacy_tier engine_ruleset_version engine_binary_hash genuine_engine
|
|
115
|
+
created_at provider model request_id response_id status surface tenant_id
|
|
116
|
+
prev_hash seq sequence canonical_sha256 chain_id receipt_hash version count].freeze
|
|
117
|
+
|
|
118
|
+
def decode_receipt_string(value)
|
|
119
|
+
parsed = begin
|
|
120
|
+
JSON.parse(value)
|
|
121
|
+
rescue JSON::ParserError
|
|
122
|
+
decoded = (value + ("=" * ((4 - value.length % 4) % 4))).tr("-_", "+/").unpack1("m0")
|
|
123
|
+
JSON.parse(decoded)
|
|
124
|
+
end
|
|
125
|
+
parsed
|
|
126
|
+
rescue ArgumentError, JSON::ParserError
|
|
127
|
+
raise ArgumentError, "receipt must use the content-free receipt envelope"
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
def validate_content_free_receipt!(value, key = nil)
|
|
131
|
+
case value
|
|
132
|
+
when Hash
|
|
133
|
+
raise ArgumentError, "receipt must be an object" if value.empty?
|
|
134
|
+
value.each do |field, child|
|
|
135
|
+
name = field.to_s
|
|
136
|
+
raise ArgumentError, "unknown receipt field" unless RECEIPT_FIELDS.include?(name)
|
|
137
|
+
validate_content_free_receipt!(child, name)
|
|
138
|
+
end
|
|
139
|
+
when Array
|
|
140
|
+
value.each { |child| validate_content_free_receipt!(child, key) }
|
|
141
|
+
when String
|
|
142
|
+
valid = case key
|
|
143
|
+
when "sig", "signature" then value.match?(/\A[A-Za-z0-9_-]{80,100}\z/)
|
|
144
|
+
when "attester_public_key" then value.match?(/\A04[0-9a-fA-F]{128}\z/)
|
|
145
|
+
when "output_sha256", "tokenised_body_hash", "engine_binary_hash", "prev_hash", "canonical_sha256", "receipt_hash"
|
|
146
|
+
value.match?(/\A[0-9a-f]{64}\z/)
|
|
147
|
+
when "detector_categories" then value.match?(/\A[A-Z][A-Z0-9_]{0,63}\z/)
|
|
148
|
+
when "no_raw_pii_egress", "genuine_engine" then false
|
|
149
|
+
when "iat", "entity_count", "file_entity_count", "seq", "sequence", "count" then false
|
|
150
|
+
else value.match?(/\A[A-Za-z0-9._:-]{1,128}\z/)
|
|
151
|
+
end
|
|
152
|
+
raise ArgumentError, "receipt contains a non-protocol string" unless valid
|
|
153
|
+
when NilClass, TrueClass, FalseClass, Numeric
|
|
154
|
+
raise ArgumentError, "receipt field has an invalid type" if %w[sig signature claims detector_categories].include?(key) && !value.nil?
|
|
155
|
+
else
|
|
156
|
+
raise ArgumentError, "receipt contains an unsupported value"
|
|
157
|
+
end
|
|
158
|
+
end
|
|
159
|
+
private :decode_receipt_string, :validate_content_free_receipt!
|
|
160
|
+
end
|
|
161
|
+
end
|
|
162
|
+
end
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require "cgi/escape"
|
|
5
|
+
|
|
6
|
+
module CloakAPI
|
|
7
|
+
module Resources
|
|
8
|
+
# Reconstruct resource (C13) — LEVEL-1, FULLY CLIENT-SIDE (local
|
|
9
|
+
# detokenisation). The gateway is a blind relay and never detokenises; raw PII
|
|
10
|
+
# NEVER egresses. Reconstruction happens ENTIRELY ON THIS MACHINE:
|
|
11
|
+
#
|
|
12
|
+
# 1. Detokenise +response_text+ locally using the caller's alias map (which
|
|
13
|
+
# holds the REAL originals) — longest-placeholder-first, never leaves the
|
|
14
|
+
# process.
|
|
15
|
+
# 2. Serialise the plaintext into the requested TEXT/STRUCTURED format
|
|
16
|
+
# (txt/md/html/csv/json/yaml/xml) using only the stdlib.
|
|
17
|
+
#
|
|
18
|
+
# BINARY/office formats (docx/pdf/xlsx/pptx) FAIL-CLOSED
|
|
19
|
+
# ({ReconstructionNotSupportedError}) — never relayed. Mirrors the Python SDK.
|
|
20
|
+
class Reconstruct
|
|
21
|
+
# Raised (fail-closed) when a BINARY/office format is requested. The Ruby
|
|
22
|
+
# SDK reconstructs only text/structured formats on-device; it never falls
|
|
23
|
+
# back to a gateway round-trip, so no alias map / PII ever egresses.
|
|
24
|
+
class ReconstructionNotSupportedError < StandardError; end
|
|
25
|
+
|
|
26
|
+
TEXT_FORMATS = %w[txt md markdown html csv json yaml yml xml].freeze
|
|
27
|
+
MIME = {
|
|
28
|
+
"txt" => "text/plain", "md" => "text/markdown", "markdown" => "text/markdown",
|
|
29
|
+
"html" => "text/html", "csv" => "text/csv", "json" => "application/json",
|
|
30
|
+
"yaml" => "text/yaml", "yml" => "text/yaml", "xml" => "application/xml"
|
|
31
|
+
}.freeze
|
|
32
|
+
EXT = { "markdown" => "md", "yml" => "yaml" }.freeze
|
|
33
|
+
|
|
34
|
+
# A reconstructed file, built fully on-device.
|
|
35
|
+
# content — file bytes
|
|
36
|
+
# content_type — MIME
|
|
37
|
+
# filename — suggested name
|
|
38
|
+
# receipt_headers — always empty (local; no gateway round-trip)
|
|
39
|
+
Result = Data.define(:content, :content_type, :filename, :receipt_headers)
|
|
40
|
+
|
|
41
|
+
def initialize(client)
|
|
42
|
+
@client = client
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# Reconstruct +response_text+ into +target_format+ FULLY ON-DEVICE. The
|
|
46
|
+
# alias map is applied locally (detokenisation); nothing is sent to the
|
|
47
|
+
# gateway. Text/structured formats only — binary/office formats fail-closed.
|
|
48
|
+
#
|
|
49
|
+
# @param response_text [String]
|
|
50
|
+
# @param alias_map [Hash] +{token => original}+ or +{"entries"=>[{placeholder,original}]}+
|
|
51
|
+
# @param target_format [String]
|
|
52
|
+
# @return [Result]
|
|
53
|
+
def create(response_text:, alias_map:, target_format:)
|
|
54
|
+
fmt = target_format.to_s.downcase
|
|
55
|
+
fmt = "txt" if fmt.empty?
|
|
56
|
+
unless TEXT_FORMATS.include?(fmt)
|
|
57
|
+
raise ReconstructionNotSupportedError,
|
|
58
|
+
"reconstruct: '#{fmt}' is a binary/office format the Ruby SDK does not build. " \
|
|
59
|
+
"Reconstruction is FULLY LOCAL — the alias map is never sent to the gateway. Use a " \
|
|
60
|
+
"text format (txt/md/html/csv/json/yaml/xml), or the TypeScript SDK / desktop app " \
|
|
61
|
+
"(which bundle the client-side engine) for office formats."
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
plaintext = detokenise_local(response_text.to_s, alias_pairs(alias_map))
|
|
65
|
+
content = build_text_format(plaintext, fmt).encode("UTF-8")
|
|
66
|
+
ext = EXT.fetch(fmt, fmt)
|
|
67
|
+
Result.new(
|
|
68
|
+
content: content,
|
|
69
|
+
content_type: MIME.fetch(fmt, "text/plain"),
|
|
70
|
+
filename: "reconstructed.#{ext}",
|
|
71
|
+
receipt_headers: {}
|
|
72
|
+
)
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
private
|
|
76
|
+
|
|
77
|
+
# Normalise the alias map to [[placeholder, original], ...]. Accepts the
|
|
78
|
+
# structured +{"entries"=>[{placeholder,original}]}+ or a flat +{token=>orig}+.
|
|
79
|
+
def alias_pairs(alias_map)
|
|
80
|
+
return [] unless alias_map.is_a?(Hash)
|
|
81
|
+
|
|
82
|
+
entries = alias_map["entries"] || alias_map[:entries]
|
|
83
|
+
if entries.is_a?(Array)
|
|
84
|
+
return entries.filter_map do |e|
|
|
85
|
+
next unless e.is_a?(Hash)
|
|
86
|
+
|
|
87
|
+
ph = e["placeholder"] || e[:placeholder]
|
|
88
|
+
og = e["original"] || e[:original]
|
|
89
|
+
[ph, og] if ph.is_a?(String) && og.is_a?(String)
|
|
90
|
+
end
|
|
91
|
+
end
|
|
92
|
+
alias_map.filter_map { |k, v| [k, v] if k.is_a?(String) && v.is_a?(String) }
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# Longest-placeholder-first substitution, entirely on-device.
|
|
96
|
+
def detokenise_local(text, pairs)
|
|
97
|
+
pairs.sort_by { |ph, _| -ph.length }.reduce(text) do |acc, (ph, og)|
|
|
98
|
+
# Block form: two-argument gsub interpolates \1 and \& in the original.
|
|
99
|
+
ph && !ph.empty? && acc.include?(ph) ? acc.gsub(ph) { og } : acc
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
def build_text_format(plaintext, fmt)
|
|
104
|
+
case fmt
|
|
105
|
+
when "json"
|
|
106
|
+
begin
|
|
107
|
+
JSON.pretty_generate(JSON.parse(plaintext))
|
|
108
|
+
rescue JSON::ParserError
|
|
109
|
+
JSON.pretty_generate({ "content" => plaintext })
|
|
110
|
+
end
|
|
111
|
+
when "html"
|
|
112
|
+
"<!doctype html>\n<html>\n<head><meta charset=\"utf-8\"></head>\n<body>\n<pre>" \
|
|
113
|
+
"#{CGI.escapeHTML(plaintext)}</pre>\n</body>\n</html>\n"
|
|
114
|
+
else
|
|
115
|
+
plaintext
|
|
116
|
+
end
|
|
117
|
+
end
|
|
118
|
+
end
|
|
119
|
+
end
|
|
120
|
+
end
|