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.
Files changed (44) 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/client.rb +1272 -0
  11. data/lib/cloakapi/degraded.rb +77 -0
  12. data/lib/cloakapi/disclosure.rb +252 -0
  13. data/lib/cloakapi/engine.rb +702 -0
  14. data/lib/cloakapi/errors.rb +65 -0
  15. data/lib/cloakapi/pii/bundled_rules.rb +670 -0
  16. data/lib/cloakapi/pii/card_spans.rb +300 -0
  17. data/lib/cloakapi/pii/detector.rb +1925 -0
  18. data/lib/cloakapi/pii/patterns.json +2238 -0
  19. data/lib/cloakapi/pii/pii_match.rb +7 -0
  20. data/lib/cloakapi/pii/pii_type.rb +7 -0
  21. data/lib/cloakapi/pii/ruleset.rb +65 -0
  22. data/lib/cloakapi/pii/tokenizer.rb +411 -0
  23. data/lib/cloakapi/posture.rb +82 -0
  24. data/lib/cloakapi/receipts.rb +406 -0
  25. data/lib/cloakapi/resources/chat.rb +82 -0
  26. data/lib/cloakapi/resources/messages.rb +90 -0
  27. data/lib/cloakapi/resources/models.rb +25 -0
  28. data/lib/cloakapi/resources/receipts.rb +162 -0
  29. data/lib/cloakapi/resources/reconstruct.rb +120 -0
  30. data/lib/cloakapi/resources/request_strings.rb +485 -0
  31. data/lib/cloakapi/resources/reviewable.rb +163 -0
  32. data/lib/cloakapi/resources/tokens.rb +28 -0
  33. data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
  34. data/lib/cloakapi/routing.rb +500 -0
  35. data/lib/cloakapi/streaming.rb +196 -0
  36. data/lib/cloakapi/surrogate_mode.rb +233 -0
  37. data/lib/cloakapi/version.rb +15 -0
  38. data/lib/cloakapi/warnings.rb +137 -0
  39. data/lib/cloakapi.rb +37 -0
  40. data/licenses/Apache-2.0.txt +202 -0
  41. data/licenses/CC-BY-4.0.txt +104 -0
  42. data/licenses/MIT-Faker.txt +21 -0
  43. data/licenses/MIT.txt +21 -0
  44. 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