flex_hold 0.1.0.pre1

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 (115) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +202 -0
  3. data/NOTICE +22 -0
  4. data/README.md +66 -0
  5. data/exe/flexhold +10 -0
  6. data/lib/flex_hold/base58.rb +36 -0
  7. data/lib/flex_hold/binding.rb +175 -0
  8. data/lib/flex_hold/cli.rb +325 -0
  9. data/lib/flex_hold/collector/canonical.rb +22 -0
  10. data/lib/flex_hold/collector/fetcher.rb +58 -0
  11. data/lib/flex_hold/collector/identity_block.rb +110 -0
  12. data/lib/flex_hold/collector/identity_verifier.rb +128 -0
  13. data/lib/flex_hold/collector/mandate_block.rb +131 -0
  14. data/lib/flex_hold/collector/mandate_verifier.rb +114 -0
  15. data/lib/flex_hold/collector/merkle.rb +31 -0
  16. data/lib/flex_hold/collector/record_block.rb +141 -0
  17. data/lib/flex_hold/collector/record_verifier.rb +134 -0
  18. data/lib/flex_hold/collector/sources.rb +116 -0
  19. data/lib/flex_hold/collector.rb +137 -0
  20. data/lib/flex_hold/consent.rb +56 -0
  21. data/lib/flex_hold/consent_log.rb +87 -0
  22. data/lib/flex_hold/eip712.rb +109 -0
  23. data/lib/flex_hold/envelope.rb +113 -0
  24. data/lib/flex_hold/jws.rb +52 -0
  25. data/lib/flex_hold/keys.rb +196 -0
  26. data/lib/flex_hold/mcp_server.rb +296 -0
  27. data/lib/flex_hold/policy/gate-policy-v1.json +1 -0
  28. data/lib/flex_hold/policy.rb +90 -0
  29. data/lib/flex_hold/presenter.rb +101 -0
  30. data/lib/flex_hold/resolvers.rb +56 -0
  31. data/lib/flex_hold/revoker.rb +48 -0
  32. data/lib/flex_hold/secp256k1.rb +115 -0
  33. data/lib/flex_hold/services.rb +231 -0
  34. data/lib/flex_hold/signer.rb +20 -0
  35. data/lib/flex_hold/status_list.rb +115 -0
  36. data/lib/flex_hold/store.rb +224 -0
  37. data/lib/flex_hold/vectors.rb +568 -0
  38. data/lib/flex_hold/verifier.rb +139 -0
  39. data/lib/flex_hold/version.rb +5 -0
  40. data/lib/flex_hold.rb +68 -0
  41. data/vectors/binding-agent-mismatch.json +42 -0
  42. data/vectors/binding-audience-mismatch.json +43 -0
  43. data/vectors/binding-audience-missing.json +42 -0
  44. data/vectors/binding-erc8004-owner-mismatch.json +47 -0
  45. data/vectors/binding-erc8004-registration-unavailable.json +46 -0
  46. data/vectors/binding-erc8004-valid.json +47 -0
  47. data/vectors/binding-expired.json +41 -0
  48. data/vectors/binding-mandate-issuer-mismatch.json +43 -0
  49. data/vectors/binding-mandate-mismatch.json +42 -0
  50. data/vectors/binding-not-yet-valid.json +41 -0
  51. data/vectors/binding-pkh-door-bound.json +43 -0
  52. data/vectors/binding-pkh-erc8004-valid.json +47 -0
  53. data/vectors/binding-pkh-valid.json +41 -0
  54. data/vectors/binding-pkh-wrong-owner.json +41 -0
  55. data/vectors/binding-revoked.json +41 -0
  56. data/vectors/binding-status-unavailable.json +39 -0
  57. data/vectors/binding-status-wrong-issuer.json +41 -0
  58. data/vectors/binding-v1-type.json +45 -0
  59. data/vectors/binding-valid-all-checks.json +46 -0
  60. data/vectors/binding-valid.json +41 -0
  61. data/vectors/binding-wrong-owner.json +41 -0
  62. data/vectors/envelope-example-v1.0.json +458 -0
  63. data/vectors/fixture-flextrust-passport-indicative-v0.1.json +323 -0
  64. data/vectors/fixture-flexyield-mandate-indicative-v0.1.json +187 -0
  65. data/vectors/identity-expired.json +24 -0
  66. data/vectors/identity-issuer-mismatch.json +24 -0
  67. data/vectors/identity-key-compromised.json +24 -0
  68. data/vectors/identity-key-unknown.json +17 -0
  69. data/vectors/identity-keys.json +20 -0
  70. data/vectors/identity-malformed-no-subject-id.json +24 -0
  71. data/vectors/identity-no-status.json +23 -0
  72. data/vectors/identity-not-yet-valid.json +24 -0
  73. data/vectors/identity-owner-mismatch.json +25 -0
  74. data/vectors/identity-revoked.json +24 -0
  75. data/vectors/identity-signature-invalid.json +24 -0
  76. data/vectors/identity-status-list-revoked.json +11 -0
  77. data/vectors/identity-status-list-valid.json +9 -0
  78. data/vectors/identity-status-list-wrong-issuer.json +9 -0
  79. data/vectors/identity-status-unavailable.json +23 -0
  80. data/vectors/identity-status-wrong-issuer.json +24 -0
  81. data/vectors/identity-valid-owner-match.json +25 -0
  82. data/vectors/identity-valid.json +24 -0
  83. data/vectors/keys.json +71 -0
  84. data/vectors/mandate-agent-mismatch.json +24 -0
  85. data/vectors/mandate-claim-overreach.json +23 -0
  86. data/vectors/mandate-expired.json +23 -0
  87. data/vectors/mandate-float-in-subject.json +23 -0
  88. data/vectors/mandate-indicative-as-delivered.json +23 -0
  89. data/vectors/mandate-issuer-mismatch.json +23 -0
  90. data/vectors/mandate-key-compromised.json +23 -0
  91. data/vectors/mandate-key-unknown.json +16 -0
  92. data/vectors/mandate-keys.json +16 -0
  93. data/vectors/mandate-not-yet-valid.json +23 -0
  94. data/vectors/mandate-receipts-inconsistent.json +23 -0
  95. data/vectors/mandate-signature-invalid.json +23 -0
  96. data/vectors/mandate-valid-agent-match.json +24 -0
  97. data/vectors/mandate-valid.json +23 -0
  98. data/vectors/record-digest-mismatch.json +350 -0
  99. data/vectors/record-expired.json +350 -0
  100. data/vectors/record-indicative-valid.json +350 -0
  101. data/vectors/record-key-compromised.json +350 -0
  102. data/vectors/record-key-unknown.json +343 -0
  103. data/vectors/record-merkle-invalid.json +350 -0
  104. data/vectors/record-not-yet-valid.json +350 -0
  105. data/vectors/record-public-tier-unsigned.json +188 -0
  106. data/vectors/record-root-mismatch.json +350 -0
  107. data/vectors/record-root-signature-invalid.json +350 -0
  108. data/vectors/record-root-unavailable.json +344 -0
  109. data/vectors/record-score-mismatch.json +350 -0
  110. data/vectors/record-signature-invalid.json +350 -0
  111. data/vectors/registration-snapshot.json +30 -0
  112. data/vectors/status-list-revoked.json +10 -0
  113. data/vectors/status-list-valid.json +8 -0
  114. data/vectors/status-list-wrong-issuer.json +9 -0
  115. metadata +217 -0
@@ -0,0 +1,325 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "thor"
4
+ require_relative "../flex_hold"
5
+
6
+ module FlexHold
7
+ # `flexhold` — the owner's command line. Private keys are files (mode 0600); the CLI prints DIDs and paths, never keys.
8
+ class CLI < Thor
9
+ class_option :json, type: :boolean, default: false, desc: "machine-readable output"
10
+
11
+ def self.exit_on_failure? = true
12
+
13
+ desc "keygen", "Create an Ed25519 key file (owner key O, or --recovery for the status-list key R)"
14
+ option :out, required: true, desc: "path of the new key file (created 0600, never overwritten)"
15
+ option :recovery, type: :boolean, default: false, desc: "label only: this is the recovery key R (keep it offline)"
16
+ option :type, default: "ed25519", desc: "ed25519 (did:key, EdDSA) or secp256k1 (an Ethereum account: did:pkh, EIP-712)"
17
+ option :chain_id, type: :numeric, default: 1, desc: "for secp256k1: the eip155 chain id in the did:pkh"
18
+ def keygen
19
+ emit(Services.keygen(out: options[:out], type: options[:type], chain_id: options[:chain_id]).merge("role" => options[:recovery] ? "recovery" : "owner"))
20
+ end
21
+
22
+ desc "sign", "Sign a binding (JSON file) with the owner key → compact JWS"
23
+ option :key, required: true, desc: "owner key file"
24
+ option :binding, required: true, desc: "binding JSON (fields: owner, agent, mandate, valid_from, valid_until, status, consent_ref, identity_refs)"
25
+ option :audience, desc: "door-bound binding: the policy_url / door id"
26
+ option :out, desc: "write the JWS here instead of stdout"
27
+ option :chain_id, type: :numeric, default: 1, desc: "for a secp256k1 key: the eip155 chain id of the owner's did:pkh"
28
+ def sign
29
+ r = Services.sign(key_path: options[:key], binding: options[:binding], audience: options[:audience], out: options[:out], chain_id: options[:chain_id])
30
+ options[:json] ? emit(r) : say(options[:out] ? "written #{options[:out]} (owner #{r['owner']})" : r["jws"])
31
+ end
32
+
33
+ desc "verify JWS_FILE", "Verify a binding offline; exit 0 = ok, 1 = a typed reason"
34
+ option :status, desc: "status-list JWS file (default: resolve the binding's file:// URL)"
35
+ option :mandate, desc: "the mandate block as presented (bytes are hashed)"
36
+ option :mandate_issuer, desc: "the mandate block's issuer as your mandate verifier established it; must equal the binding's mandate.issuer (v1.1)"
37
+ option :registration, desc: "ERC-8004 registration snapshot JSON"
38
+ option :request_key, desc: "DID of the key that signed the request (Web Bot Auth)"
39
+ option :audience, desc: "this door's policy_url / id"
40
+ def verify(jws_file)
41
+ r = Services.verify(jws: jws_file, status: options[:status], mandate: options[:mandate], mandate_issuer: options[:mandate_issuer], registration: options[:registration],
42
+ request_key_id: options[:request_key], audience: options[:audience])
43
+ options[:json] ? emit(r) : say("#{r['ok'] ? 'ok' : 'FAIL'} #{r['reason']} — checks: #{r['checks'].map { |k, v| "#{k}=#{v}" }.join(' ')}")
44
+ exit(r["ok"] ? 0 : 1)
45
+ end
46
+
47
+ desc "revoke", "Set the binding's status bit: the recovery key R re-issues the status list"
48
+ option :recovery_key, required: true
49
+ option :status_list, required: true, desc: "status-list JWS file (re-written atomically)"
50
+ option :index, required: true, type: :numeric
51
+ def revoke
52
+ emit(Services.revoke(recovery_key_path: options[:recovery_key], status_list: options[:status_list], index: options[:index]))
53
+ end
54
+
55
+ # H3 · present_passport: one envelope for one door. Passphrase: FLEXHOLD_STORE_PASSPHRASE or --passphrase-file (never argv).
56
+ desc "present", "Write one Agent Passport Envelope (v1.0) for a door from the store: the agent's blocks by role, minimum disclosure; logs `presented`"
57
+ option :store, required: true, desc: "store directory"
58
+ option :agent, required: true, desc: "the agent key K (did:key / Web Bot Auth key id) that presents the envelope"
59
+ option :roles, desc: "comma-separated roles: mandate,record,binding,identity — overrides the policy (default: the policy's roles, else every single role present; identity only on ask)"
60
+ option :policy, desc: "the door's gate policy as a file or https URL (gate-policy-v1): its keys name the roles (bound → binding, the rest → record)"
61
+ option :also, desc: "comma-separated roles added on top of the policy (the mandate and identity credentials are presented only when asked for)"
62
+ option :policy_url, desc: "the door's published gate policy URL: read for the roles unless --roles is given; carried in the envelope and logged as `to`"
63
+ option :audience, desc: "door id when the presentation is door-bound (`aud`)"
64
+ option :agent_key, desc: "agent key PEM for the offline `proof` (file form only; the agent normally signs the request instead)"
65
+ option :out, desc: "write the envelope document here (file form)"
66
+ option :header, type: :boolean, default: false, desc: "print only the `Agent-Passport:` header line (data form, ≤ 32 KB)"
67
+ option :passphrase_file
68
+ def present
69
+ r = Services.present(store: options[:store], agent: options[:agent], roles: options[:roles], policy: options[:policy], also: options[:also], policy_url: options[:policy_url],
70
+ audience: options[:audience], agent_key_path: options[:agent_key], out: options[:out], passphrase_file: options[:passphrase_file])
71
+ if options[:header]
72
+ say(Envelope.header(r["envelope"]))
73
+ elsif options[:json]
74
+ emit(r)
75
+ else
76
+ say("presented #{r['roles'].join(' + ')} for #{options[:agent]} as #{r['presentation_id']} (#{r['bytes']} bytes#{r['out'] ? ", written #{r['out']}" : ''})")
77
+ end
78
+ rescue PresentationRefused, PolicyRejected => e
79
+ say(options[:json] ? JSON.pretty_generate({ "ok" => false, "reason" => e.reason.to_s, "message" => e.message }) : "REFUSED #{e.message}")
80
+ exit 1
81
+ end
82
+
83
+ # H3.2 · the policy reader on its own: what a door's policy asks the passport for.
84
+ class PolicyCmd < Thor
85
+ def self.exit_on_failure? = true
86
+
87
+ desc "read SOURCE", "Read a door's gate policy (gate-policy-v1; file or https URL) → the roles the presenter would disclose; unknown keys are refused"
88
+ def read(source)
89
+ r = Services.policy_read(source: source)
90
+ options[:json] ? say(JSON.pretty_generate(r)) : say("roles: #{r['roles'].join(' + ')} — #{r['fields'].map { |k, v| "#{k}=#{v}" }.join(' ')} (#{r['version']}, #{r['hash']})")
91
+ rescue PolicyRejected => e
92
+ say(options[:json] ? JSON.pretty_generate({ "ok" => false, "reason" => e.reason.to_s, "message" => e.message }) : "REFUSED #{e.message}")
93
+ exit 1
94
+ end
95
+ end
96
+
97
+ class StatusListCmd < Thor
98
+ def self.exit_on_failure? = true
99
+
100
+ desc "init", "Issue the first (empty) status list with the recovery key"
101
+ option :recovery_key, required: true
102
+ option :url, required: true, desc: "where verifiers will fetch it (named in every binding)"
103
+ option :out, required: true
104
+ def init = parent_emit(Services.status_list_init(recovery_key_path: options[:recovery_key], url: options[:url], out: options[:out]))
105
+
106
+ desc "refresh", "Re-issue the list with a fresh validity window"
107
+ option :recovery_key, required: true
108
+ option :path, required: true
109
+ def refresh = parent_emit(Services.status_list_refresh(recovery_key_path: options[:recovery_key], path: options[:path]))
110
+
111
+ no_commands do
112
+ def parent_emit(h) = say(JSON.pretty_generate(h))
113
+ end
114
+ end
115
+
116
+ class VectorsCmd < Thor
117
+ def self.exit_on_failure? = true
118
+
119
+ desc "verify", "Run every committed test vector through signer + verifier"
120
+ option :dir, default: Vectors::DEFAULT_DIR
121
+ def verify
122
+ r = Services.vectors_verify(dir: options[:dir])
123
+ if options[:json]
124
+ say(JSON.pretty_generate(r))
125
+ else
126
+ r["results"].each { |x| say("#{x['ok'] ? 'ok ' : 'FAIL'} #{x['name']} (#{x['expected']})") }
127
+ say("#{r['ok'] ? 'all' : 'NOT all'} #{r['count']} vectors reproduce and verify")
128
+ end
129
+ exit(r["ok"] ? 0 : 1)
130
+ end
131
+ end
132
+
133
+ class RecordCmd < Thor
134
+ def self.exit_on_failure? = true
135
+
136
+ desc "verify FILE", "Verify a FlexTrust record block (passport-v1) offline: window, key, digest, merkle, root, freshness"
137
+ option :keys, desc: "key directory: file or https URL (/.well-known/flextrust); none = nothing is trusted"
138
+ option :commitments, desc: "daily commitments: file or https URL (/commitments.json)"
139
+ option :now, desc: "verification time, RFC 3339 (default: now)"
140
+ def verify(file)
141
+ r = Services.record_verify(path: file, keys: options[:keys], commitments: options[:commitments], now: options[:now])
142
+ options[:json] ? say(JSON.pretty_generate(r)) : say("#{r['ok'] ? 'ok' : 'FAIL'} #{r['reason']} — checks: #{r['checks'].map { |k, v| "#{k}=#{v}" }.join(' ')}")
143
+ exit(r["ok"] ? 0 : 1)
144
+ end
145
+
146
+ desc "collect REF", "Fetch a FlexTrust record block (agent id → public passport, a flextrust.io URL, or a file), verify it, wrap it as a collected block"
147
+ option :keys, desc: "key directory: file or https URL (default for remote refs: the live /.well-known/flextrust)"
148
+ option :commitments, desc: "daily commitments: file or https URL (default for remote refs: the live /commitments.json)"
149
+ option :now, desc: "verification time, RFC 3339 (default: now)"
150
+ option :out, desc: "write the collected block (document + verdict) to this file"
151
+ def collect(ref)
152
+ h = Services.record_collect(ref: ref, keys: options[:keys], commitments: options[:commitments], now: options[:now], out: options[:out])
153
+ v = h["verification"]
154
+ options[:json] ? say(JSON.pretty_generate(h)) : say("#{v['ok'] ? 'ok' : 'FAIL'} #{v['reason']} — #{h['ref']}#{h['out'] ? " → #{h['out']}" : ''}")
155
+ exit(v["ok"] ? 0 : 1)
156
+ end
157
+ end
158
+
159
+ desc "status-list SUBCOMMAND", "init | refresh the status list (status_list works too)"
160
+ subcommand "status_list", StatusListCmd
161
+
162
+ desc "record SUBCOMMAND", "verify | collect a FlexTrust record block (H2 collector)"
163
+ subcommand "record", RecordCmd
164
+
165
+ class MandateCmd < Thor
166
+ def self.exit_on_failure? = true
167
+
168
+ desc "verify FILE", "Verify a FlexYield mandate block (mandate-v1 compact JWS, or its JSON wrapper) offline: key, issuer, window, subject, claim, receipts"
169
+ option :keys, desc: "JWK Set with validity: file or https URL; none = nothing is trusted"
170
+ option :now, desc: "verification time, RFC 3339 (default: now)"
171
+ option :agent, desc: "the agent key K your binding names; the mandate's subject must be this key"
172
+ def verify(file)
173
+ r = Services.mandate_verify(path: file, keys: options[:keys], now: options[:now], agent: options[:agent])
174
+ options[:json] ? say(JSON.pretty_generate(r)) : say("#{r['ok'] ? 'ok' : 'FAIL'} #{r['reason']} — checks: #{r['checks'].map { |k, v| "#{k}=#{v}" }.join(' ')}")
175
+ exit(r["ok"] ? 0 : 1)
176
+ end
177
+
178
+ desc "collect REF", "Fetch a FlexYield mandate block (a flexyield.io URL, or a file: JSON wrapper or bare JWS), verify it, wrap it as a collected block"
179
+ option :keys, desc: "JWK Set with validity: file or https URL (default for remote refs: the issuer's /.well-known/flexyield)"
180
+ option :now, desc: "verification time, RFC 3339 (default: now)"
181
+ option :agent, desc: "the agent key K your binding names"
182
+ option :out, desc: "write the collected block (document + verdict) to this file"
183
+ def collect(ref)
184
+ h = Services.mandate_collect(ref: ref, keys: options[:keys], now: options[:now], agent: options[:agent], out: options[:out])
185
+ v = h["verification"]
186
+ options[:json] ? say(JSON.pretty_generate(h)) : say("#{v['ok'] ? 'ok' : 'FAIL'} #{v['reason']} — #{h['ref']}#{h['out'] ? " → #{h['out']}" : ''}")
187
+ exit(v["ok"] ? 0 : 1)
188
+ end
189
+ end
190
+
191
+ desc "mandate SUBCOMMAND", "verify | collect a FlexYield mandate block (H2 collector)"
192
+ subcommand "mandate", MandateCmd
193
+
194
+ # H2.3 · an owner-identity credential (jwt_vc_json: W3C VC 2.0 as a compact JWS) from any issuer; the issuer's JWK Set is the trust.
195
+ class IdentityCmd < Thor
196
+ def self.exit_on_failure? = true
197
+
198
+ desc "verify FILE", "Verify an owner-identity credential (jwt_vc_json compact JWS, or its JSON wrapper) offline: key, issuer, window, subject, status"
199
+ option :keys, desc: "the ISSUER's JWK Set with validity: file or https URL; none = nothing is trusted"
200
+ option :status, desc: "the issuer's status-list JWS as a file (for a credentialStatus entry); default: file:// lists resolve, https ones read status_unavailable"
201
+ option :now, desc: "verification time, RFC 3339 (default: now)"
202
+ option :owner, desc: "the owner DID O your binding names; the credential's subject must be O"
203
+ def verify(file)
204
+ r = Services.identity_verify(path: file, keys: options[:keys], status: options[:status], now: options[:now], owner: options[:owner])
205
+ options[:json] ? say(JSON.pretty_generate(r)) : say("#{r['ok'] ? 'ok' : 'FAIL'} #{r['reason']} — checks: #{r['checks'].map { |k, v| "#{k}=#{v}" }.join(' ')}")
206
+ exit(r["ok"] ? 0 : 1)
207
+ end
208
+
209
+ desc "collect REF", "Fetch an owner-identity credential (an https URL of any issuer — JSON wrapper {jws} — or a file: wrapper or bare JWS), verify it, wrap it as a collected block"
210
+ option :keys, desc: "the ISSUER's JWK Set with validity: file or https URL (required in practice; no default — the issuer is a third party)"
211
+ option :status, desc: "the issuer's status-list JWS as a file"
212
+ option :now, desc: "verification time, RFC 3339 (default: now)"
213
+ option :owner, desc: "the owner DID O your binding names"
214
+ option :out, desc: "write the collected block (document + verdict) to this file"
215
+ def collect(ref)
216
+ h = Services.identity_collect(ref: ref, keys: options[:keys], status: options[:status], now: options[:now], owner: options[:owner], out: options[:out])
217
+ v = h["verification"]
218
+ options[:json] ? say(JSON.pretty_generate(h)) : say("#{v['ok'] ? 'ok' : 'FAIL'} #{v['reason']} — #{h['ref']}#{h['out'] ? " → #{h['out']}" : ''}")
219
+ exit(v["ok"] ? 0 : 1)
220
+ end
221
+ end
222
+
223
+ desc "identity SUBCOMMAND", "verify | collect an owner-identity credential, jwt_vc_json (H2.3 collector)"
224
+ subcommand "identity", IdentityCmd
225
+
226
+ # H4 · the owner's encrypted local store. Passphrase: FLEXHOLD_STORE_PASSPHRASE or --passphrase-file (never on the command line).
227
+ class StoreCmd < Thor
228
+ def self.exit_on_failure? = true
229
+ class_option :store, required: true, desc: "store directory (one per owner)"
230
+ class_option :passphrase_file, desc: "0600 file holding the passphrase (default: FLEXHOLD_STORE_PASSPHRASE)"
231
+
232
+ desc "init", "Create an empty encrypted store for an owner"
233
+ option :owner, required: true, desc: "the owner's DID (did:key or did:pkh)"
234
+ def init = emit(Services.store_init(store: options[:store], owner: options[:owner], passphrase_file: options[:passphrase_file]))
235
+
236
+ desc "add FILE", "Consent to and store a collected block (record/mandate/identity collect --out) or a binding JWS; prints the item id and consent_ref"
237
+ def add(file) = emit(Services.store_add(store: options[:store], path: file, passphrase_file: options[:passphrase_file]))
238
+
239
+ desc "list", "List the items (kinds, ids, hashes, agents — never the credentials)"
240
+ def list
241
+ r = Services.store_list(store: options[:store], passphrase_file: options[:passphrase_file])
242
+ return emit(r) if options[:json]
243
+
244
+ say("store #{r['store_id']} · owner #{r['owner']} · #{r['items'].size} item(s)")
245
+ r["items"].each { |i| say("#{i['id']} #{i['kind'].ljust(8)} #{i['added_at']} #{i['content_hash'][0, 23]}… #{(Array(i['agents']) + [ i['subject'] ]).compact.join(' ')}#{i['withdrawn_at'] ? " WITHDRAWN #{i['withdrawn_at']}" : ''}") }
246
+ end
247
+
248
+ desc "show ID", "Show one item in full (the owner's own data)"
249
+ def show(id) = emit(Services.store_show(store: options[:store], id: id, passphrase_file: options[:passphrase_file]))
250
+
251
+ desc "export", "Write a portable bundle (still encrypted) with the consent log"
252
+ option :out, required: true
253
+ def export = emit(Services.store_export(store: options[:store], out: options[:out], passphrase_file: options[:passphrase_file]))
254
+
255
+ desc "import BUNDLE", "Import a bundle into a new store directory (passphrase and log chain are checked first)"
256
+ def import(bundle) = emit(Services.store_import(bundle: bundle, store: options[:store], passphrase_file: options[:passphrase_file]))
257
+
258
+ no_commands do
259
+ def emit(h) = say(JSON.pretty_generate(h))
260
+ end
261
+ end
262
+
263
+ class ConsentCmd < Thor
264
+ def self.exit_on_failure? = true
265
+ class_option :store, required: true, desc: "store directory"
266
+
267
+ desc "log", "Print the consent log (append-only, hash-chained; references and hashes only)"
268
+ def log
269
+ r = Services.consent_log(store: options[:store])
270
+ return say(JSON.pretty_generate(r)) if options[:json]
271
+
272
+ r["entries"].each { |e| say("#{e['seq'].to_s.rjust(4)} #{e['at']} #{e['event'].ljust(17)} #{e['subject']} #{e['detail'].reject { |k, _| k == 'items' }.map { |k, v| "#{k}=#{v}" }.join(' ')}") }
273
+ say(r["ok"] ? "chain ok (#{r['count']} entries, head #{r['head'][0, 12]}…)" : "CHAIN BROKEN at entry #{r['broken_at']}")
274
+ exit(r["ok"] ? 0 : 1)
275
+ end
276
+
277
+ desc "verify", "Verify the consent log chain"
278
+ def verify
279
+ r = Services.consent_log(store: options[:store])
280
+ say(options[:json] ? JSON.pretty_generate(r.reject { |k, _| k == "entries" }) : (r["ok"] ? "ok #{r['count']} entries, head #{r['head']}" : "BROKEN at entry #{r['broken_at']}"))
281
+ exit(r["ok"] ? 0 : 1)
282
+ end
283
+
284
+ desc "withdraw", "Withdraw consent for an item or an agent: logs it and revokes every binding that rests on it (recovery key R)"
285
+ option :item, desc: "item id (its dependent bindings are revoked too)"
286
+ option :agent, desc: "agent key / id: every item of that agent"
287
+ option :recovery_key, required: true, desc: "the recovery key R file that issues the status list"
288
+ option :reason
289
+ option :passphrase_file
290
+ def withdraw
291
+ emit(Services.consent_withdraw(store: options[:store], recovery_key_path: options[:recovery_key], item: options[:item], agent: options[:agent],
292
+ reason: options[:reason], passphrase_file: options[:passphrase_file]))
293
+ end
294
+
295
+ no_commands do
296
+ def emit(h) = say(JSON.pretty_generate(h))
297
+ end
298
+ end
299
+
300
+ desc "store SUBCOMMAND", "init | add | list | show | export | import — the owner's encrypted local store (H4)"
301
+ subcommand "store", StoreCmd
302
+
303
+ desc "policy SUBCOMMAND", "read a door's gate policy → roles (H3.2 policy reader)"
304
+ subcommand "policy", PolicyCmd
305
+
306
+ desc "consent SUBCOMMAND", "log | verify | withdraw — the append-only consent log (H4)"
307
+ subcommand "consent", ConsentCmd
308
+
309
+ desc "vectors SUBCOMMAND", "verify the test vectors"
310
+ subcommand "vectors", VectorsCmd
311
+
312
+ desc "mcp", "Start the local stdio MCP server (tools: sign, verify, revoke, verify_record, collect_record, verify_mandate, collect_mandate, verify_identity, collect_identity, store_*, consent_*, present_passport, read_gate_policy)"
313
+ def mcp
314
+ require_relative "mcp_server"
315
+ MCPServer.build.start
316
+ end
317
+
318
+ desc "version", "Print the gem version"
319
+ def version = say(FlexHold::VERSION)
320
+
321
+ no_commands do
322
+ def emit(h) = say(JSON.pretty_generate(h))
323
+ end
324
+ end
325
+ end
@@ -0,0 +1,22 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ module Collector
5
+ # FlexTrust's documentDigest convention (spec /spec/passport, pinned 2026-10-27 against the indicative fixture):
6
+ # sha256 over the credentialSubject serialised with keys sorted at every level and no whitespace. The signed subject
7
+ # carries no floats (integers, basis points, strings), so JSON.generate of scalars is unambiguous.
8
+ module Canonical
9
+ module_function
10
+
11
+ def json(value)
12
+ case value
13
+ when Hash then "{" + value.keys.sort.map { |k| JSON.generate(k.to_s) + ":" + json(value[k]) }.join(",") + "}"
14
+ when Array then "[" + value.map { |v| json(v) }.join(",") + "]"
15
+ else JSON.generate(value)
16
+ end
17
+ end
18
+
19
+ def sha256_hex(value) = Digest::SHA256.hexdigest(json(value))
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+ require "uri"
5
+
6
+ module FlexHold
7
+ module Collector
8
+ # How the collector reaches an issuer: https only, bounded in time and size, JSON only. Injectable, so tests and
9
+ # vectors never dial out (Static).
10
+ module Fetcher
11
+ class HTTPS
12
+ JSON_TYPES = %r{\Aapplication/(ld\+)?json(\s*;|\z)}
13
+ attr_reader :timeout, :max_bytes
14
+
15
+ def initialize(timeout: 10, max_bytes: 1_048_576)
16
+ @timeout, @max_bytes = timeout, max_bytes
17
+ end
18
+
19
+ def call(url)
20
+ uri = parse!(url)
21
+ res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: timeout, read_timeout: timeout) do |http|
22
+ http.get(uri.request_uri, "Accept" => "application/json", "User-Agent" => "flexhold/#{FlexHold::VERSION}")
23
+ end
24
+ accept!(res.code.to_i, res["content-type"], res.body.to_s)
25
+ rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError, IOError => e
26
+ raise FetchFailed, "#{uri.host}: #{e.class.name.split('::').last}"
27
+ end
28
+
29
+ # The boundary for anything that came over the wire.
30
+ def accept!(code, content_type, body)
31
+ raise FetchFailed, "HTTP #{code}" unless code == 200
32
+ raise FetchFailed, "not JSON (#{content_type})" unless content_type.to_s.match?(JSON_TYPES)
33
+ raise FetchFailed, "body larger than #{max_bytes} bytes" if body.bytesize > max_bytes
34
+
35
+ JSON.parse(body)
36
+ rescue JSON::ParserError
37
+ raise Malformed, "response is not valid JSON"
38
+ end
39
+
40
+ private
41
+
42
+ def parse!(url)
43
+ uri = URI.parse(url.to_s)
44
+ raise Malformed, "only https URLs are fetched" unless uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty?
45
+
46
+ uri
47
+ rescue URI::InvalidURIError
48
+ raise Malformed, "not a URL"
49
+ end
50
+ end
51
+
52
+ class Static
53
+ def initialize(map) = @map = map
54
+ def call(url) = @map.fetch(url) { raise FetchFailed, "no static response for #{url}" }
55
+ end
56
+ end
57
+ end
58
+ end
@@ -0,0 +1,110 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ module Collector
5
+ # H2.3 · an owner-identity credential in the `jwt_vc_json` format (Christian, 2026-11-07): a W3C VC 2.0 credential secured as a
6
+ # compact JWS (EdDSA, typ vc+jwt), issued by a third party about the OWNER O — never about the agent. FlexHold references it
7
+ # (the binding's `identity_refs` carry the credential `id`) and never re-issues (DISTRIBUTION §1). Issuer-neutral by design:
8
+ # the shape is VC 2.0 + JOSE, the type `OwnerIdentity` is recommended, the subject's claims are the issuer's business and are
9
+ # never interpreted here (the summary lists claim NAMES only). Parsed once at the boundary; every shape error one Malformed.
10
+ class IdentityBlock
11
+ CONTEXT_VC = "https://www.w3.org/ns/credentials/v2"
12
+ TYPE_BASE = "VerifiableCredential"
13
+ TYPE_ROLE = "OwnerIdentity" # ENVELOPE E1 role type, recommended for issuers that know the envelope
14
+ STATUS_TYPE = "BitstringStatusListEntry"
15
+ DID_RE = MandateBlock::DID_RE
16
+ KID_RE = MandateBlock::KID_RE
17
+
18
+ attr_reader :jws, :header, :payload, :subject
19
+
20
+ # doc: the compact JWS as a String, or a Hash carrying "jws" (a collected block, an issuer's wrapper).
21
+ def self.from_document(doc)
22
+ jws = doc.is_a?(Hash) ? doc["jws"] : doc
23
+ raise Malformed, "identity document must be a compact JWS or an object with a jws" unless jws.is_a?(String) && jws.count(".") == 2
24
+
25
+ header, payload = JWS.decode(jws.strip)
26
+ new(jws.strip, header, payload)
27
+ end
28
+
29
+ def initialize(jws, header, payload)
30
+ @jws, @header, @payload = jws, header, payload
31
+ validate!
32
+ @subject = payload["credentialSubject"]
33
+ end
34
+
35
+ def kid = header["kid"]
36
+ def kid_did = kid[KID_RE, 1]
37
+ def issuer = payload["issuer"].is_a?(Hash) ? payload["issuer"]["id"] : payload["issuer"]
38
+ def iss = payload["iss"]
39
+ def sub = payload["sub"]
40
+ def id = payload["id"]
41
+ def type = payload["type"]
42
+ def nbf = payload["nbf"]
43
+ def exp = payload["exp"]
44
+ def iat = payload["iat"]
45
+ def subject_id = subject["id"]
46
+ def status = payload["credentialStatus"]
47
+ def status? = !status.nil?
48
+ def status_url = status && status["statusListCredential"]
49
+ def status_index = status && Integer(status["statusListIndex"])
50
+ def credential_hash = "sha256:" + Digest::SHA256.hexdigest(jws)
51
+ def claim_keys = (subject.keys - [ "id" ]).sort
52
+
53
+ # What a holder shows about an identity credential: who issued what kind of credential to whom, until when — claim names, never values.
54
+ def summary
55
+ { "id" => id, "issuer" => issuer, "type" => type, "subject" => subject_id, "claim_keys" => claim_keys,
56
+ "valid_until" => payload["validUntil"] || Time.at(exp).utc.strftime("%Y-%m-%dT%H:%M:%SZ"), "status" => status? ? status_url : nil,
57
+ "credential_hash" => credential_hash }
58
+ end
59
+
60
+ private
61
+
62
+ def validate!
63
+ bad!("header.alg must be #{JWS::ALG}") unless header["alg"] == JWS::ALG
64
+ bad!("header.typ must be #{JWS::TYP_VC}") unless header["typ"] == JWS::TYP_VC
65
+ bad!("header.kid must be <did>#<fragment>") unless header["kid"].is_a?(String) && header["kid"].match?(KID_RE)
66
+ p = payload
67
+ bad!("payload must be an object") unless p.is_a?(Hash)
68
+ bad!("@context must start with #{CONTEXT_VC}") unless p["@context"].is_a?(Array) && p["@context"].first == CONTEXT_VC
69
+ bad!("type must be an array including #{TYPE_BASE}") unless p["type"].is_a?(Array) && p["type"].include?(TYPE_BASE) && p["type"].all? { |t| str?(t) }
70
+ bad!("issuer must be a DID or {id: DID}") unless did?(p["issuer"]) || (p["issuer"].is_a?(Hash) && did?(p["issuer"]["id"]))
71
+ bad!("id must be a string") unless str?(p["id"])
72
+ bad!("iss must be a DID") unless did?(p["iss"])
73
+ bad!("sub must be a DID") unless did?(p["sub"])
74
+ bad!("nbf and exp must be integers") unless p["nbf"].is_a?(Integer) && p["exp"].is_a?(Integer)
75
+ bad!("iat must be an integer") unless p["iat"].nil? || p["iat"].is_a?(Integer)
76
+ bad!("exp must be after nbf") unless p["exp"] > p["nbf"]
77
+ agree!("validFrom", p["validFrom"], p["nbf"])
78
+ agree!("validUntil", p["validUntil"], p["exp"])
79
+ cs = p["credentialSubject"]
80
+ bad!("credentialSubject must be an object with a DID id") unless cs.is_a?(Hash) && did?(cs["id"])
81
+ bad!("credentialSubject.id must equal sub") unless cs["id"] == p["sub"]
82
+ status!(p["credentialStatus"]) unless p["credentialStatus"].nil?
83
+ end
84
+
85
+ # validFrom must be the same instant as nbf (validUntil as exp): two spellings of one fact, never two facts (H2.2 rule).
86
+ def agree!(name, string, epoch)
87
+ return if string.nil?
88
+
89
+ bad!("#{name} must be an RFC 3339 timestamp") unless string.is_a?(String)
90
+ t = begin
91
+ Time.iso8601(string).to_i
92
+ rescue ArgumentError
93
+ bad!("#{name} must be an RFC 3339 timestamp")
94
+ end
95
+ bad!("#{name} (#{string}) disagrees with #{name == 'validFrom' ? 'nbf' : 'exp'} (#{epoch})") unless t == epoch
96
+ end
97
+
98
+ def status!(s)
99
+ bad!("credentialStatus must be a #{STATUS_TYPE}") unless s.is_a?(Hash) && s["type"] == STATUS_TYPE
100
+ bad!("credentialStatus.statusPurpose must be revocation") unless s["statusPurpose"] == "revocation"
101
+ bad!("credentialStatus.statusListCredential must be a URL") unless str?(s["statusListCredential"])
102
+ bad!("credentialStatus.statusListIndex must be a non-negative integer") unless s["statusListIndex"].to_s.match?(/\A\d+\z/)
103
+ end
104
+
105
+ def str?(v) = v.is_a?(String) && !v.strip.empty?
106
+ def did?(v) = v.is_a?(String) && v.match?(DID_RE)
107
+ def bad!(msg) = raise(Malformed, msg)
108
+ end
109
+ end
110
+ end
@@ -0,0 +1,128 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ module Collector
5
+ # H2.3 · verifies an owner-identity credential (jwt_vc_json) offline against the issuer's JWK Set the caller hands in — any issuer,
6
+ # nothing trusted by default. Five checks, each failure one typed reason; the checks hash shows what ran. The optional status
7
+ # check reads a W3C Bitstring Status List the ISSUER signs (verified with the same JWK Set, so did:web issuers work); the guarded
8
+ # StatusList module is reused read-only for the bitstring.
9
+ # Reasons: :ok, :malformed, :key_unknown, :key_compromised, :signature_invalid, :issuer_mismatch, :not_yet_valid, :expired,
10
+ # :owner_mismatch, :status_unavailable, :status_invalid, :revoked
11
+ class IdentityVerifier
12
+ CHECKS = %i[key issuer window subject status].freeze
13
+
14
+ Result = Struct.new(:reason, :block, :checks, keyword_init: true) do
15
+ def ok? = reason == :ok
16
+ def to_h = { "ok" => ok?, "reason" => reason.to_s, "checks" => checks.transform_keys(&:to_s).transform_values(&:to_s), "block" => block&.summary }
17
+ end
18
+
19
+ def initialize(jwk_directory:, status_resolver: nil, now: -> { Time.now }, expected_owner: nil)
20
+ @jwk_directory, @status_resolver, @now, @expected_owner = jwk_directory, status_resolver, now, expected_owner
21
+ end
22
+
23
+ def verify(doc)
24
+ checks = CHECKS.to_h { |c| [ c, :skipped ] }
25
+ block = nil
26
+ reason = catch(:fail) do
27
+ block = parse(doc)
28
+ check_key(block, checks)
29
+ check_issuer(block, checks)
30
+ check_window(block, checks)
31
+ check_subject(block, checks)
32
+ check_status(block, checks)
33
+ :ok
34
+ end
35
+ Result.new(reason: reason, block: block, checks: checks)
36
+ end
37
+
38
+ private
39
+
40
+ def fail!(reason, checks, check)
41
+ checks[check] = :failed
42
+ throw :fail, reason
43
+ end
44
+
45
+ def parse(doc)
46
+ IdentityBlock.from_document(doc)
47
+ rescue Malformed
48
+ throw :fail, :malformed
49
+ end
50
+
51
+ # 1 · kid is a directory key valid at issuance, and the Ed25519 signature verifies with it
52
+ def check_key(block, checks)
53
+ state, key = JwkDirectory.key_at(@jwk_directory, block.kid, at: block.iat || block.nbf)
54
+ fail!(state, checks, :key) unless state == :ok
55
+ begin
56
+ JWS.verify(block.jws, key)
57
+ rescue SignatureInvalid, Malformed
58
+ fail!(:signature_invalid, checks, :key)
59
+ end
60
+ checks[:key] = :passed
61
+ end
62
+
63
+ # 2 · iss == issuer == the DID the kid belongs to
64
+ def check_issuer(block, checks)
65
+ fail!(:issuer_mismatch, checks, :issuer) unless block.iss == block.issuer && block.issuer == block.kid_did
66
+ checks[:issuer] = :passed
67
+ end
68
+
69
+ # 3 · nbf ≤ now < exp
70
+ def check_window(block, checks)
71
+ now = @now.call.to_i
72
+ fail!(:not_yet_valid, checks, :window) if now < block.nbf
73
+ fail!(:expired, checks, :window) unless now < block.exp
74
+ checks[:window] = :passed
75
+ end
76
+
77
+ # 4 · the subject is the owner the caller's binding names (subject.id == sub is the parser's)
78
+ def check_subject(block, checks)
79
+ fail!(:owner_mismatch, checks, :subject) if @expected_owner && block.subject_id != @expected_owner
80
+ checks[:subject] = :passed
81
+ end
82
+
83
+ # 5 · credentialStatus, when present: the issuer's status list resolves, verifies with a directory key, is in its window, bit clear
84
+ def check_status(block, checks)
85
+ return unless block.status?
86
+
87
+ fail!(:status_unavailable, checks, :status) if @status_resolver.nil?
88
+ list_jws = begin
89
+ @status_resolver.call(block.status_url)
90
+ rescue StatusUnavailable
91
+ fail!(:status_unavailable, checks, :status)
92
+ end
93
+ list = begin
94
+ parse_status_list(list_jws, block)
95
+ rescue Malformed, SignatureInvalid, ArgumentError, TypeError
96
+ fail!(:status_invalid, checks, :status)
97
+ end
98
+ fail!(:status_invalid, checks, :status) if list.nil?
99
+ begin
100
+ fail!(:revoked, checks, :status) if list.set?(block.status_index)
101
+ rescue Malformed
102
+ fail!(:status_invalid, checks, :status)
103
+ end
104
+ checks[:status] = :passed
105
+ end
106
+
107
+ # The list is a BitstringStatusListCredential signed by the credential's ISSUER with a key from the same JWK Set. → Bitstring or nil
108
+ def parse_status_list(jws, block)
109
+ header, claims = JWS.decode(jws)
110
+ return nil unless claims["iss"] == block.issuer && claims["issuer"] == block.issuer
111
+ return nil unless claims["type"] == StatusList::Credential::TYPE
112
+
113
+ state, key = JwkDirectory.key_at(@jwk_directory, header["kid"], at: claims["nbf"] || claims["iat"])
114
+ return nil unless state == :ok
115
+
116
+ JWS.verify(jws, key)
117
+ cs = claims["credentialSubject"]
118
+ return nil unless cs.is_a?(Hash) && cs["statusPurpose"] == "revocation"
119
+
120
+ from, to = Time.iso8601(claims["validFrom"]).to_i, Time.iso8601(claims["validUntil"]).to_i
121
+ now = @now.call.to_i
122
+ return nil unless from <= now && now < to
123
+
124
+ StatusList::Bitstring.decode(cs["encodedList"])
125
+ end
126
+ end
127
+ end
128
+ end