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,568 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ # JSON test vectors (vectors/): generated deterministically from TEST-ONLY seeds, shipped in the gem, copied to
5
+ # docs/bridge/vectors/ for the siblings. Runner = what `flexhold vectors verify` and test/guarded run.
6
+ module Vectors
7
+ KEY_SEEDS = {
8
+ "owner" => "flexhold-test-vector-owner-key-O",
9
+ "recovery" => "flexhold-test-vector-recovery-key",
10
+ "other" => "flexhold-test-vector-other-key-X",
11
+ "agent" => "flexhold-test-vector-agent-key-K",
12
+ "owner_pkh" => "flexhold-test-vector-owner-wallet-O-secp256k1",
13
+ "other_pkh" => "flexhold-test-vector-other-wallet-X-secp256k1"
14
+ }.freeze
15
+ PKH_CHAIN_ID = 1
16
+ NOW = Time.utc(2026, 10, 26, 12, 0, 0)
17
+ DEFAULT_DIR = File.expand_path("../../vectors", __dir__)
18
+ STATUS_URL = "https://status.flexhold.example/lists/1.jws" # resolved from the vector files, never fetched
19
+ REGISTRY = "0x" + "ab" * 20
20
+ # H2.3 · the test identity ISSUER (did:key; seed published in identity-keys.json, never in keys.json — the binding keys stay as published)
21
+ IDENTITY_ISSUER_SEED = "flexhold-test-vector-identity-issuer-key-I"
22
+ IDENTITY_STATUS_URL = "https://status.identity.example/lists/1.jws"
23
+ IDENTITY_NOW = Time.utc(2026, 10, 27, 12, 0, 0)
24
+
25
+ def self.identity_issuer = Keys::Ed25519.from_seed(Digest::SHA256.digest(IDENTITY_ISSUER_SEED))
26
+
27
+ # Ed25519 keys from a 32-byte seed; secp256k1 keys ("*_pkh") from the same bytes as the private scalar.
28
+ def self.key(name)
29
+ bytes = Digest::SHA256.digest(KEY_SEEDS.fetch(name))
30
+ name.end_with?("_pkh") ? Keys::Secp256k1.from_private_bytes(bytes, chain_id: PKH_CHAIN_ID) : Keys::Ed25519.from_seed(bytes)
31
+ end
32
+
33
+ class Runner
34
+ Outcome = Struct.new(:name, :signature_ok, :verdict_ok, :expected, :actual, keyword_init: true) do
35
+ def ok? = signature_ok && verdict_ok
36
+ end
37
+
38
+ def initialize(dir) = @dir = dir
39
+
40
+ def names = Dir[File.join(@dir, "binding-*.json")].sort.map { |p| File.basename(p, ".json") }
41
+
42
+ def run
43
+ names.map { |n| run_one(n) }
44
+ end
45
+
46
+ def run_one(name)
47
+ v = load(name)
48
+ exp = v.fetch("expected")
49
+ sig_ok = v["forged"] ? true : (resign(v) == exp["jws"])
50
+ result = verify(v)
51
+ Outcome.new(name: name, signature_ok: sig_ok, verdict_ok: result.reason.to_s == exp["reason"] && result.ok? == exp["ok"],
52
+ expected: exp["reason"], actual: result.reason.to_s)
53
+ end
54
+
55
+ def load(name)
56
+ JSON.parse(File.read(File.join(@dir, "#{name}.json")))
57
+ end
58
+
59
+ def resign(v)
60
+ i = v.fetch("inputs")
61
+ key = Vectors.key(i["signing_key"])
62
+ if i["type"] # a vector that pins an older type array (v1: no `AgentBinding`) — same claims, the type overridden, same key
63
+ claims = Binding.from_h(i["binding"]).to_claims(jti: i["jti"], iat: Time.iso8601(i["iat"]), nonce: i["nonce"], audience: i["audience"])
64
+ return JWS.sign(claims.merge("type" => i["type"]), key)
65
+ end
66
+ Signer.new(owner_key: key).sign(Binding.from_h(i["binding"]), jti: i["jti"], iat: Time.iso8601(i["iat"]), nonce: i["nonce"], audience: i["audience"])
67
+ end
68
+
69
+ def verify(v)
70
+ vv = v.fetch("verify")
71
+ status_map = vv["status_list"] ? { Vectors::STATUS_URL => load(vv["status_list"]).fetch("jws") } : {}
72
+ registration = vv["registration"] && Resolvers::StaticRegistration.new(
73
+ load(vv["registration"]).fetch("registrations").to_h { |r| [ Resolvers::StaticRegistration.key_for(r), r["owner"] ] }
74
+ )
75
+ now = Time.iso8601(v.fetch("now"))
76
+ Verifier.new(status_resolver: Resolvers::StaticStatus.new(status_map), registration_resolver: registration, now: -> { now })
77
+ .verify(v.fetch("expected").fetch("jws"),
78
+ mandate_bytes: vv["mandate_bytes_b64"] && Base64.strict_decode64(vv["mandate_bytes_b64"]), mandate_issuer: vv["mandate_issuer"],
79
+ request_key_id: vv["request_key_id"], audience: vv["audience"])
80
+ end
81
+ end
82
+
83
+ # H2 · record vectors (record-*.json): the collector's verdict on a FlexTrust record block. Derived from the indicative
84
+ # fixture by mutation — FlexHold holds no FlexTrust key, so nothing is re-signed; the runner checks verdicts only.
85
+ class RecordRunner
86
+ Outcome = Struct.new(:name, :verdict_ok, :expected, :actual, keyword_init: true) do
87
+ def ok? = verdict_ok
88
+ end
89
+
90
+ def initialize(dir) = @dir = dir
91
+
92
+ def names = Dir[File.join(@dir, "record-*.json")].sort.map { |p| File.basename(p, ".json") }
93
+
94
+ def run = names.map { |n| run_one(n) }
95
+
96
+ def run_one(name)
97
+ v = JSON.parse(File.read(File.join(@dir, "#{name}.json")))
98
+ exp = v.fetch("expected")
99
+ result = Collector::RecordVerifier.new(key_directory: Collector::KeyDirectory::Static.new(v.fetch("key_directory")),
100
+ commitments: Collector::Commitments::Static.new(v.fetch("commitments")),
101
+ now: -> { Time.iso8601(v.fetch("now")) }).verify(v.fetch("block"))
102
+ Outcome.new(name: name, verdict_ok: result.reason.to_s == exp["reason"] && result.ok? == exp["ok"], expected: exp["reason"], actual: result.reason.to_s)
103
+ end
104
+ end
105
+
106
+ # H2.2 · mandate vectors (mandate-*.json): the collector's verdict on a FlexYield mandate block. The valid cases are re-signed
107
+ # with FlexYield's published TEST seed over the delivered payload (byte-exact parity); the delivered fixture is committed as delivered.
108
+ class MandateRunner
109
+ Outcome = Struct.new(:name, :verdict_ok, :expected, :actual, keyword_init: true) do
110
+ def ok? = verdict_ok
111
+ end
112
+
113
+ def initialize(dir) = @dir = dir
114
+
115
+ def names = Dir[File.join(@dir, "mandate-*.json")].sort.map { |p| File.basename(p, ".json") } - [ "mandate-keys" ]
116
+
117
+ def run = names.map { |n| run_one(n) }
118
+
119
+ def run_one(name)
120
+ v = JSON.parse(File.read(File.join(@dir, "#{name}.json")))
121
+ exp = v.fetch("expected")
122
+ result = Collector::MandateVerifier.new(jwk_directory: Collector::JwkDirectory::Static.new(v.fetch("jwk_directory")),
123
+ now: -> { Time.iso8601(v.fetch("now")) }, expected_agent: v["expected_agent"]).verify(v.fetch("document"))
124
+ Outcome.new(name: name, verdict_ok: result.reason.to_s == exp["reason"] && result.ok? == exp["ok"], expected: exp["reason"], actual: result.reason.to_s)
125
+ end
126
+ end
127
+
128
+ # H2.3 · identity vectors (identity-*.json): the collector's verdict on an owner-identity credential (jwt_vc_json) from the test
129
+ # issuer I over the vectors' owner O. `status_list` names the issuer's status-list vector the resolver serves; none = unavailable.
130
+ class IdentityRunner
131
+ Outcome = Struct.new(:name, :verdict_ok, :expected, :actual, keyword_init: true) do
132
+ def ok? = verdict_ok
133
+ end
134
+
135
+ def initialize(dir) = @dir = dir
136
+
137
+ def names = Dir[File.join(@dir, "identity-*.json")].sort.map { |p| File.basename(p, ".json") }.reject { |n| n == "identity-keys" || n.start_with?("identity-status-list-") }
138
+
139
+ def run = names.map { |n| run_one(n) }
140
+
141
+ def run_one(name)
142
+ v = load(name)
143
+ exp = v.fetch("expected")
144
+ lists = v["status_list"] ? load(v["status_list"]).then { |l| { l.fetch("url") => l.fetch("jws") } } : {}
145
+ result = Collector::IdentityVerifier.new(jwk_directory: Collector::JwkDirectory::Static.new(v.fetch("jwk_directory")), status_resolver: Resolvers::StaticStatus.new(lists),
146
+ now: -> { Time.iso8601(v.fetch("now")) }, expected_owner: v["expected_owner"]).verify(v.fetch("document"))
147
+ Outcome.new(name: name, verdict_ok: result.reason.to_s == exp["reason"] && result.ok? == exp["ok"], expected: exp["reason"], actual: result.reason.to_s)
148
+ end
149
+
150
+ def load(name) = JSON.parse(File.read(File.join(@dir, "#{name}.json")))
151
+ end
152
+
153
+ # H3 · envelope vectors (envelope-*.json): the example envelope FlexYield's door verifier runs (acceptance #2). The runner rebuilds
154
+ # the document from `inputs` (binding re-signed with the test owner key; mandate and record taken from the named vectors) and
155
+ # compares bytes, then runs FlexHold's own three verifiers over the blocks at `now` — the door's cross-checks are the door's.
156
+ class EnvelopeRunner
157
+ Outcome = Struct.new(:name, :rebuilt, :blocks, keyword_init: true) do
158
+ def ok? = rebuilt && blocks.values.all? { |v| v == "ok" }
159
+ def actual = (rebuilt ? "rebuilt" : "DIFFERS") + " · " + blocks.map { |k, v| "#{k}=#{v}" }.join(" ")
160
+ end
161
+
162
+ def initialize(dir) = @dir = dir
163
+
164
+ def names = Dir[File.join(@dir, "envelope-*.json")].sort.map { |p| File.basename(p, ".json") }
165
+
166
+ def run = names.map { |n| run_one(n) }
167
+
168
+ def run_one(name)
169
+ v = load(name)
170
+ i = v.fetch("inputs")
171
+ now = Time.iso8601(v.fetch("now"))
172
+ mandate_vector, record_vector = load(i.fetch("mandate")), load(i.fetch("record"))
173
+ mandate_jws = mandate_vector.fetch("document").fetch("jws")
174
+ record = record_vector.fetch("block")
175
+ b = i.fetch("binding")
176
+ binding_jws = Signer.new(owner_key: Vectors.key(b.fetch("signing_key"))).sign(Binding.from_h(b.fetch("binding")), jti: b["jti"], iat: Time.iso8601(b["iat"]), nonce: b["nonce"])
177
+ env = Envelope.build(holder: i.fetch("holder"), mandate_jws: mandate_jws, record: record, binding_jws: binding_jws, policy_url: i["policy_url"], audience: i["audience"],
178
+ nonce: i.fetch("nonce"), presented_at: now)
179
+ expected = v.fetch("expected").fetch("envelope")
180
+ vv = v.fetch("verify")
181
+ blocks = {
182
+ "mandate" => Collector::MandateVerifier.new(jwk_directory: Collector::JwkDirectory::Static.new(vv.fetch("mandate").fetch("jwk_directory")), now: -> { now }, expected_agent: i["holder"]).verify(mandate_jws).reason.to_s,
183
+ "record" => Collector::RecordVerifier.new(key_directory: Collector::KeyDirectory::Static.new(vv.fetch("record").fetch("key_directory")),
184
+ commitments: Collector::Commitments::Static.new(vv.fetch("record").fetch("commitments")), now: -> { now }).verify(record).reason.to_s,
185
+ "binding" => binding_verdict(vv.fetch("binding"), binding_jws, mandate_jws, i["holder"], now)
186
+ }
187
+ Outcome.new(name: name, rebuilt: Collector::Canonical.json(env) == Collector::Canonical.json(expected), blocks: blocks)
188
+ end
189
+
190
+ private
191
+
192
+ def load(name) = JSON.parse(File.read(File.join(@dir, "#{name}.json")))
193
+
194
+ def binding_verdict(spec, jws, mandate_jws, holder, now)
195
+ status = { Vectors::STATUS_URL => load(spec.fetch("status_list")).fetch("jws") }
196
+ registration = Resolvers::StaticRegistration.new(load(spec.fetch("registration")).fetch("registrations").to_h { |r| [ Resolvers::StaticRegistration.key_for(r), r["owner"] ] })
197
+ Verifier.new(status_resolver: Resolvers::StaticStatus.new(status), registration_resolver: registration, now: -> { now })
198
+ .verify(jws, mandate_bytes: mandate_jws, mandate_issuer: JWS.decode(mandate_jws).last["iss"], request_key_id: holder).reason.to_s
199
+ end
200
+ end
201
+
202
+ class Generator
203
+ MANDATE_BYTES = "{\"mandate\":\"fixture — the #9 export stands in here\"}"
204
+ FIXTURE_NAME = "fixture-flextrust-passport-indicative-v0.1.json"
205
+ FIXTURE_SOURCE = File.join(Vectors::DEFAULT_DIR, FIXTURE_NAME)
206
+ MANDATE_FIXTURE_NAME = "fixture-flexyield-mandate-indicative-v0.1.json"
207
+ MANDATE_FIXTURE_SOURCE = File.join(Vectors::DEFAULT_DIR, MANDATE_FIXTURE_NAME)
208
+ MANDATE_NOW = Time.utc(2026, 10, 27, 12, 0, 0)
209
+ RECORD_NOW = Time.utc(2026, 10, 26, 18, 30, 0)
210
+ RECORD_TEST_KEY = "indicative-test-key"
211
+ RECORD_TEST_KEY_ADDRESS = "0xE5B5595C2f11306CD43D725CE8b98707a139BbBd" # recovered from the fixture's statement signature
212
+ RECORD_LEAF_COUNT = 10_657 # the synthetic agent is the last leaf (position 10656); the fixture itself carries no leaf count
213
+
214
+ def initialize(dir, fixture_source: FIXTURE_SOURCE, mandate_fixture_source: MANDATE_FIXTURE_SOURCE)
215
+ @dir, @fixture_source, @mandate_fixture_source = dir, fixture_source, mandate_fixture_source
216
+ end
217
+
218
+ def run
219
+ FileUtils.mkdir_p(@dir)
220
+ write_keys
221
+ write_status_lists
222
+ write_registration
223
+ bindings.each { |name, spec| write_binding(name, spec) }
224
+ write_record_vectors
225
+ write_mandate_vectors
226
+ write_identity_vectors
227
+ write_envelope_example
228
+ Dir[File.join(@dir, "*.json")].sort.map { |p| File.basename(p) }
229
+ end
230
+
231
+ private
232
+
233
+ def fixture = JSON.parse(File.read(@fixture_source))
234
+ def mandate_fixture = JSON.parse(File.read(@mandate_fixture_source))
235
+
236
+ def copy_fixture(source, name)
237
+ target = File.join(@dir, name)
238
+ FileUtils.cp(source, target) unless File.expand_path(source) == File.expand_path(target)
239
+ end
240
+
241
+ # FlexYield's test key from its published seed; the header carries FlexYield's kid, not a did:key one.
242
+ def mandate_key = Keys::Ed25519.from_seed(Digest::SHA256.digest(mandate_fixture["key"]["seed_string"]))
243
+
244
+ def sign_mandate(payload, kid: mandate_fixture["key"]["kid"])
245
+ header = { "alg" => "EdDSA", "typ" => "vc+jwt", "kid" => kid }
246
+ input = "#{JWS.b64url(JSON.generate(header))}.#{JWS.b64url(JSON.generate(payload))}"
247
+ "#{input}.#{JWS.b64url(mandate_key.sign(input))}"
248
+ end
249
+
250
+ # FlexYield regenerated the fixture 2026-10-28 (day offset fixed): the payload is used as delivered; re-signing it with the
251
+ # published seed reproduces the delivered JWS byte-exact (FINDINGS 2026-10-27 / 2026-10-28).
252
+ def mandate_payload = mandate_fixture["payload"]
253
+
254
+ def write_mandate_vectors
255
+ copy_fixture(@mandate_fixture_source, MANDATE_FIXTURE_NAME)
256
+ f = mandate_fixture
257
+ kid = f["key"]["kid"]
258
+ entry = { "x" => f["key"]["jwk"]["x"], "valid_from" => "2026-10-27", "retired_at" => nil, "compromised_at" => nil }
259
+ write("mandate-keys", {
260
+ "test_only" => true,
261
+ "warning" => "FlexYield's indicative test key (seed published in its fixture); never trust it for anything real.",
262
+ "shape" => "JWK Set with validity — the shape FlexHold reads for an issuer's signing keys (kid, kty OKP, crv Ed25519, x, valid_from, retired_at, compromised_at)",
263
+ "keys" => [ { "kid" => kid, "kty" => "OKP", "crv" => "Ed25519", "x" => f["key"]["jwk"]["x"], "valid_from" => "2026-10-27", "retired_at" => nil, "compromised_at" => nil } ]
264
+ })
265
+ keys = { kid => entry }
266
+ agent = f["payload"]["credentialSubject"]["id"]
267
+ mandate_vectors(keys, agent).each do |name, spec|
268
+ write(name, {
269
+ "name" => name, "description" => spec[:desc], "spec" => "docs/spec/collector-v1.md", "source" => "flexyield",
270
+ "note" => spec[:note] || "payload = FlexYield's indicative fixture as delivered (10-28 regeneration), re-signed with the published test seed — byte-equal to the delivered JWS; verdict only",
271
+ "now" => iso(spec[:now] || MANDATE_NOW), "jwk_directory" => spec.fetch(:keys, keys), "expected_agent" => spec[:agent],
272
+ "document" => { "jws" => spec[:jws] }, "expected" => { "ok" => spec[:ok], "reason" => spec[:reason] }
273
+ }.compact)
274
+ end
275
+ end
276
+
277
+ def mandate_vectors(keys, agent)
278
+ p = mandate_payload
279
+ kid = mandate_fixture["key"]["kid"]
280
+ subject = ->(**changes) { sign_mandate(p.merge("credentialSubject" => p["credentialSubject"].merge(changes))) }
281
+ claim = p["credentialSubject"]["principal"]
282
+ receipts = p["credentialSubject"]["receipts"]
283
+ valid = sign_mandate(p)
284
+ h, b, s = valid.split(".")
285
+ flipped = JWS.b64url(JWS.b64url_decode(s).tap { |x| x.setbyte(0, x.getbyte(0) ^ 1) })
286
+ {
287
+ "mandate-indicative-as-delivered" => { desc: "FlexYield's fixture exactly as regenerated 2026-10-28 (day offset fixed): iat/nbf/exp agree with claimed_at/validFrom/validUntil → ok. Until 10-28 this vector carried the 10-27 file and expected malformed (one-day offset)",
288
+ note: "document unchanged from the bridge delivery; byte-equal to mandate-valid (generator parity)", jws: mandate_fixture["jws"], ok: true, reason: "ok" },
289
+ "mandate-valid" => { desc: "the delivered payload re-signed with the published seed (byte-equal to the delivered JWS), all six checks pass", jws: valid, ok: true, reason: "ok" },
290
+ "mandate-valid-agent-match" => { desc: "the caller names the binding's agent key K and the subject is K", jws: valid, agent: agent, ok: true, reason: "ok" },
291
+ "mandate-agent-mismatch" => { desc: "the caller names another agent key", jws: valid, agent: Vectors.key("other").did, ok: false, reason: "agent_mismatch" },
292
+ "mandate-expired" => { desc: "verified after exp", jws: valid, now: Time.utc(2026, 12, 1, 0, 0, 0), ok: false, reason: "expired" },
293
+ "mandate-not-yet-valid" => { desc: "verified before nbf", jws: valid, now: Time.utc(2026, 10, 27, 9, 0, 0), ok: false, reason: "not_yet_valid" },
294
+ "mandate-key-unknown" => { desc: "the JWK Set does not list the kid", jws: valid, keys: {}, ok: false, reason: "key_unknown" },
295
+ "mandate-key-compromised" => { desc: "the key was marked compromised before issuance", jws: valid, ok: false, reason: "key_compromised",
296
+ keys: { kid => keys[kid].merge("compromised_at" => "2026-10-27T09:00:00Z") } },
297
+ "mandate-signature-invalid" => { desc: "one bit of the signature flipped", jws: "#{h}.#{b}.#{flipped}", ok: false, reason: "signature_invalid" },
298
+ "mandate-issuer-mismatch" => { desc: "iss names another DID than issuer.id and the kid", jws: sign_mandate(p.merge("iss" => "did:web:other.example")), ok: false, reason: "issuer_mismatch" },
299
+ "mandate-claim-overreach" => { desc: "the claim asserts ownership — a FlexYield claim may only mandate (DISTRIBUTION v1.2)", ok: false, reason: "claim_overreach",
300
+ jws: subject.("principal" => claim.merge("claim" => claim["claim"].merge("asserts_ownership" => true))) },
301
+ "mandate-receipts-inconsistent" => { desc: "verdict counts do not add up to count", ok: false, reason: "receipts_inconsistent",
302
+ jws: subject.("receipts" => receipts.merge("verdicts" => receipts["verdicts"].merge("inside" => receipts["verdicts"]["inside"] - 1))) },
303
+ "mandate-float-in-subject" => { desc: "a float in the signed subject (money must be cents, counts integers)", ok: false, reason: "malformed",
304
+ jws: subject.("mandate" => p["credentialSubject"]["mandate"].merge("fences" => { "rate_per_minute" => 120.0, "daily_cents" => 500 })) }
305
+ }
306
+ end
307
+
308
+ # H2.3 · identity vectors: the test issuer I signs a jwt_vc_json credential about the vectors' owner O (did:key); the status list
309
+ # is I's own (BitstringStatusListCredential), so the status check verifies it with I's JWK Set — the did:web path real issuers take.
310
+ def i = Vectors.identity_issuer
311
+ def identity_now = Vectors::IDENTITY_NOW
312
+
313
+ def identity_payload(**over)
314
+ id = "urn:uuid:00000000-0000-4000-8000-#{Digest::SHA256.hexdigest('identity-valid')[0, 12]}"
315
+ {
316
+ "@context" => [ "https://www.w3.org/ns/credentials/v2" ], "type" => [ "VerifiableCredential", "OwnerIdentity" ], "id" => id, "issuer" => i.did,
317
+ "validFrom" => "2026-10-27T10:00:00Z", "validUntil" => "2026-11-27T10:00:00Z",
318
+ "credentialSubject" => { "id" => o.did, "verification_level" => "test" },
319
+ "credentialStatus" => { "type" => "BitstringStatusListEntry", "statusPurpose" => "revocation", "statusListIndex" => 5, "statusListCredential" => Vectors::IDENTITY_STATUS_URL },
320
+ "iss" => i.did, "sub" => o.did, "jti" => id, "iat" => 1_793_095_200, "nbf" => 1_793_095_200, "exp" => 1_795_773_600
321
+ }.merge(over)
322
+ end
323
+
324
+ def write_identity_vectors
325
+ base = { "url" => Vectors::IDENTITY_STATUS_URL, "valid_from" => iso(identity_now - 3600), "valid_for" => 86_400, "note" => "the identity ISSUER's own status list (BitstringStatusListCredential), verified with the issuer's JWK Set — not the binding's list" }
326
+ valid_list = StatusList::Credential.issue(issuer_key: i, url: Vectors::IDENTITY_STATUS_URL, valid_from: identity_now - 3600, valid_for: 86_400)
327
+ write("identity-status-list-valid", base.merge("issuer" => i.did, "revoked_indexes" => [], "jws" => valid_list))
328
+ revoked_list = StatusList::Credential.parse(valid_list, expected_issuer: i.did, now: identity_now).with_revoked(5, issuer_key: i, valid_from: identity_now - 3600, valid_for: 86_400)
329
+ write("identity-status-list-revoked", base.merge("issuer" => i.did, "revoked_indexes" => [ 5 ], "jws" => revoked_list))
330
+ wrong_list = StatusList::Credential.issue(issuer_key: x, url: Vectors::IDENTITY_STATUS_URL, valid_from: identity_now - 3600, valid_for: 86_400)
331
+ write("identity-status-list-wrong-issuer", base.merge("issuer" => x.did, "note" => "signed by a key that is not the credential issuer's", "revoked_indexes" => [], "jws" => wrong_list))
332
+
333
+ entry = { "x" => i.to_jwk["x"], "valid_from" => "2026-10-27", "retired_at" => nil, "compromised_at" => nil }
334
+ keys = { i.kid => entry }
335
+ write("identity-keys", {
336
+ "test_only" => true,
337
+ "warning" => "FlexHold's TEST identity issuer I (seed published here); never trust it for anything real. Real issuers are third parties — their JWK Set is the trust.",
338
+ "seed_rule" => "seed = SHA-256(seed_string) → Ed25519 private key", "seed_string" => Vectors::IDENTITY_ISSUER_SEED, "did" => i.did, "kid" => i.kid,
339
+ "shape" => "JWK Set with validity — the shape FlexHold reads for an issuer's signing keys (kid, kty OKP, crv Ed25519, x, valid_from, retired_at, compromised_at)",
340
+ "keys" => [ { "kid" => i.kid, "kty" => "OKP", "crv" => "Ed25519", "x" => i.to_jwk["x"], "valid_from" => "2026-10-27", "retired_at" => nil, "compromised_at" => nil } ]
341
+ })
342
+ identity_vectors(keys).each do |name, spec|
343
+ write(name, {
344
+ "name" => name, "description" => spec[:desc], "spec" => "docs/spec/collector-v1.md", "source" => "identity",
345
+ "note" => spec[:note] || "a jwt_vc_json owner-identity credential (W3C VC 2.0 as a compact JWS, EdDSA) by the test issuer I about owner O; verdict only — the subject's claims are never interpreted",
346
+ "now" => iso(spec[:now] || identity_now), "jwk_directory" => spec.fetch(:keys, keys), "expected_owner" => spec[:owner], "status_list" => spec.fetch(:list, "identity-status-list-valid"),
347
+ "document" => { "jws" => spec[:jws] }, "expected" => { "ok" => spec[:ok], "reason" => spec[:reason] }
348
+ }.compact)
349
+ end
350
+ end
351
+
352
+ def identity_vectors(keys)
353
+ valid = JWS.sign(identity_payload, i)
354
+ h, b, sig = valid.split(".")
355
+ flipped = JWS.b64url(JWS.b64url_decode(sig).bytes.tap { |bytes| bytes[0] ^= 1 }.pack("C*"))
356
+ entry = keys.values.first
357
+ {
358
+ "identity-valid" => { desc: "a jwt_vc_json owner-identity credential by issuer I about owner O, status list clear — all five checks pass", jws: valid, ok: true, reason: "ok" },
359
+ "identity-valid-owner-match" => { desc: "the caller names the binding's owner O and the subject is O", jws: valid, owner: o.did, ok: true, reason: "ok" },
360
+ "identity-no-status" => { desc: "a credential without credentialStatus: the status check is skipped, the rest passes", jws: JWS.sign(identity_payload.tap { |p| p.delete("credentialStatus") }, i), list: nil, ok: true, reason: "ok" },
361
+ "identity-owner-mismatch" => { desc: "the caller names another owner (X)", jws: valid, owner: x.did, ok: false, reason: "owner_mismatch" },
362
+ "identity-expired" => { desc: "verified after exp", jws: valid, now: Time.utc(2026, 12, 1, 0, 0, 0), ok: false, reason: "expired" },
363
+ "identity-not-yet-valid" => { desc: "verified before nbf", jws: valid, now: Time.utc(2026, 10, 27, 9, 0, 0), ok: false, reason: "not_yet_valid" },
364
+ "identity-key-unknown" => { desc: "the JWK Set does not list the kid", jws: valid, keys: {}, ok: false, reason: "key_unknown" },
365
+ "identity-key-compromised" => { desc: "the key was marked compromised before issuance", jws: valid, keys: { i.kid => entry.merge("compromised_at" => "2026-10-27T09:00:00Z") }, ok: false, reason: "key_compromised" },
366
+ "identity-signature-invalid" => { desc: "one bit of the signature flipped", jws: "#{h}.#{b}.#{flipped}", ok: false, reason: "signature_invalid" },
367
+ "identity-issuer-mismatch" => { desc: "iss names another DID than issuer and the kid", jws: JWS.sign(identity_payload("iss" => x.did), i), ok: false, reason: "issuer_mismatch" },
368
+ "identity-revoked" => { desc: "the issuer's status list has bit 5 set", jws: valid, list: "identity-status-list-revoked", ok: false, reason: "revoked" },
369
+ "identity-status-unavailable" => { desc: "credentialStatus names a list that cannot be resolved", jws: valid, list: nil, ok: false, reason: "status_unavailable" },
370
+ "identity-status-wrong-issuer" => { desc: "the status list is signed by a key that is not the credential issuer's", jws: valid, list: "identity-status-list-wrong-issuer", ok: false, reason: "status_invalid" },
371
+ "identity-malformed-no-subject-id" => { desc: "credentialSubject without a DID id (sub cannot be matched)", jws: JWS.sign(identity_payload("credentialSubject" => { "verification_level" => "test" }), i), ok: false, reason: "malformed" }
372
+ }
373
+ end
374
+
375
+ def write_record_vectors
376
+ copy_fixture(@fixture_source, FIXTURE_NAME)
377
+ root = fixture.dig("statement", "proof", "root")
378
+ keys = { RECORD_TEST_KEY => { "address" => RECORD_TEST_KEY_ADDRESS, "valid_from" => "2026-10-26", "retired_at" => nil, "compromised_at" => nil } }
379
+ roots = { "2026-10-26" => { "merkle_root" => root, "leaf_count" => RECORD_LEAF_COUNT, "methodology_version" => "v1" } }
380
+ record_vectors(keys, roots).each do |name, spec|
381
+ block = fixture
382
+ spec[:mutate]&.call(block)
383
+ write(name, {
384
+ "name" => name, "description" => spec[:desc], "spec" => "docs/spec/collector-v1.md", "source" => "flextrust",
385
+ "note" => "derived from FlexTrust's indicative fixture (ephemeral test key #{RECORD_TEST_KEY}); verdict only, nothing re-signed",
386
+ "now" => iso(spec[:now] || RECORD_NOW), "key_directory" => spec.fetch(:keys, keys), "commitments" => spec.fetch(:roots, roots),
387
+ "block" => block, "expected" => { "ok" => spec[:ok], "reason" => spec[:reason] }
388
+ })
389
+ end
390
+ end
391
+
392
+ def record_vectors(keys, roots)
393
+ {
394
+ "record-indicative-valid" => { desc: "the indicative full-tier passport, all six checks pass", ok: true, reason: "ok" },
395
+ "record-public-tier-unsigned" => { desc: "public tier: no statement, no proof — proves nothing by design", ok: false, reason: "unsigned",
396
+ mutate: ->(b) { %w[statement proof print_url].each { |k| b.delete(k) }; b["tier"] = "public" } },
397
+ "record-expired" => { desc: "verified after validUntil", now: Time.utc(2026, 10, 28, 0, 0, 0), ok: false, reason: "expired" },
398
+ "record-not-yet-valid" => { desc: "verified before issuedAt", now: Time.utc(2026, 10, 26, 18, 0, 0), ok: false, reason: "not_yet_valid" },
399
+ "record-key-unknown" => { desc: "the key directory does not list the statement's keyId", keys: {}, ok: false, reason: "key_unknown" },
400
+ "record-key-compromised" => { desc: "the key was marked compromised before issuance", ok: false, reason: "key_compromised",
401
+ keys: { RECORD_TEST_KEY => keys[RECORD_TEST_KEY].merge("compromised_at" => "2026-10-26T18:00:00Z") } },
402
+ "record-signature-invalid" => { desc: "one byte of the statement signature changed", ok: false, reason: "signature_invalid",
403
+ mutate: ->(b) { b["statement"]["signature"] = b["statement"]["signature"].sub(/\A0x../, "0x00") } },
404
+ "record-digest-mismatch" => { desc: "the subject was changed after signing (score 712 → 713)", ok: false, reason: "digest_mismatch",
405
+ mutate: ->(b) { b["credentialSubject"]["score"]["value"] = 713 } },
406
+ "record-merkle-invalid" => { desc: "one sibling in the inclusion proof changed", ok: false, reason: "merkle_invalid",
407
+ mutate: ->(b) { b["statement"]["proof"]["siblings"][3] = "00" * 32 } },
408
+ "record-root-unavailable" => { desc: "no commitment published for the day", roots: {}, ok: false, reason: "root_unavailable" },
409
+ "record-root-mismatch" => { desc: "the published root for the day differs", ok: false, reason: "root_mismatch",
410
+ roots: { "2026-10-26" => roots["2026-10-26"].merge("merkle_root" => "11" * 32) } },
411
+ "record-root-signature-invalid" => { desc: "the published leaf count differs, so the CommitmentRoot signature recovers to another address", ok: false, reason: "root_signature_invalid",
412
+ roots: { "2026-10-26" => roots["2026-10-26"].merge("leaf_count" => RECORD_LEAF_COUNT + 1) } },
413
+ "record-score-mismatch" => { desc: "committed_score differs from the signed score", ok: false, reason: "score_mismatch",
414
+ mutate: ->(b) { b["statement"]["committed_score"]["value"] = 700 } }
415
+ }
416
+ end
417
+
418
+ def o = Vectors.key("owner")
419
+ def r = Vectors.key("recovery")
420
+ def x = Vectors.key("other")
421
+ def k = Vectors.key("agent")
422
+ def iso(t) = t.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
423
+
424
+ def write(name, h)
425
+ File.write(File.join(@dir, "#{name}.json"), JSON.pretty_generate(h) + "\n")
426
+ end
427
+
428
+ def write_keys
429
+ write("keys", {
430
+ "test_only" => true,
431
+ "warning" => "Test vectors only. Seeds are public; never use these keys for anything real.",
432
+ "seed_rule" => "seed = SHA-256(seed_string) → Ed25519 private key; for *_pkh keys the same 32 bytes are the secp256k1 private scalar (chain id 1)",
433
+ "keys" => Vectors::KEY_SEEDS.to_h do |n, s|
434
+ key = Vectors.key(n)
435
+ entry = { "seed_string" => s, "seed_hex" => Digest::SHA256.hexdigest(s), "did" => key.did, "kid" => key.kid, "alg" => key.alg }
436
+ entry[key.is_a?(Keys::Ed25519) ? "jwk" : "address"] = key.is_a?(Keys::Ed25519) ? key.to_jwk : key.address
437
+ [ n, entry ]
438
+ end
439
+ })
440
+ end
441
+
442
+ def write_status_lists
443
+ base = { "url" => Vectors::STATUS_URL, "valid_from" => iso(Vectors::NOW - 3600), "valid_for" => 86_400 }
444
+ valid = StatusList::Credential.issue(issuer_key: r, url: Vectors::STATUS_URL, valid_from: Vectors::NOW - 3600, valid_for: 86_400)
445
+ write("status-list-valid", base.merge("issuer" => r.did, "revoked_indexes" => [], "jws" => valid))
446
+ revoked = StatusList::Credential.parse(valid, expected_issuer: r.did, now: Vectors::NOW)
447
+ .with_revoked(7, issuer_key: r, valid_from: Vectors::NOW - 3600, valid_for: 86_400)
448
+ write("status-list-revoked", base.merge("issuer" => r.did, "revoked_indexes" => [ 7 ], "jws" => revoked))
449
+ wrong = StatusList::Credential.issue(issuer_key: x, url: Vectors::STATUS_URL, valid_from: Vectors::NOW - 3600, valid_for: 86_400)
450
+ write("status-list-wrong-issuer", base.merge("issuer" => x.did, "note" => "signed by a key the binding does not name", "revoked_indexes" => [], "jws" => wrong))
451
+ end
452
+
453
+ def write_registration
454
+ write("registration-snapshot", {
455
+ "note" => "stands in for any signed ERC-8004 registration snapshot; the snapshot signature check is the caller's",
456
+ "registrations" => [
457
+ { "chain_id" => 1, "registry" => Vectors::REGISTRY, "agent_id" => "42", "owner" => o.did },
458
+ { "chain_id" => 1, "registry" => Vectors::REGISTRY, "agent_id" => "43", "owner" => x.did },
459
+ { "chain_id" => 1, "registry" => Vectors::REGISTRY, "agent_id" => "44", "owner" => Vectors.key("owner_pkh").did },
460
+ { "chain_id" => 8453, "registry" => Vectors::REGISTRY, "agent_id" => "999999001", "owner" => o.did, "note" => "the record vectors' synthetic agent, registered to O for the example envelope" }
461
+ ]
462
+ })
463
+ end
464
+
465
+ # H3 · the example envelope: one consistent passport from the valid vectors. `now` 2026-10-27T10:30Z sits inside the record
466
+ # window (10-26T18:12 → 10-27T18:12), after the mandate's nbf (10-27T10:00) and before status-list-valid expires (10-27T11:00).
467
+ ENVELOPE_NOW = Time.utc(2026, 10, 27, 10, 30, 0)
468
+ ENVELOPE_REGISTRY = Vectors::REGISTRY
469
+
470
+ def write_envelope_example
471
+ name = "envelope-example-v1.0"
472
+ mandate = JSON.parse(File.read(File.join(@dir, "mandate-valid.json")))
473
+ record = JSON.parse(File.read(File.join(@dir, "record-indicative-valid.json")))
474
+ mandate_jws = mandate.fetch("document").fetch("jws")
475
+ _, claims = JWS.decode(mandate_jws)
476
+ subject_id = record.fetch("block").fetch("credentialSubject").fetch("id") # erc8004:<chain>:<agent>
477
+ _, chain, agent_id = subject_id.split(":")
478
+ b = binding("agent" => { "key_id" => k.did, "erc8004" => { "chain_id" => Integer(chain), "registry" => ENVELOPE_REGISTRY, "agent_id" => agent_id } },
479
+ "mandate" => { "hash" => "sha256:" + Digest::SHA256.hexdigest(mandate_jws), "issuer" => claims["iss"], "version" => "1" },
480
+ "valid_from" => iso(ENVELOPE_NOW - 1800), "valid_until" => iso(ENVELOPE_NOW + 86_400 - 1800))
481
+ inputs = { "holder" => k.did, "mandate" => "mandate-valid", "record" => "record-indicative-valid",
482
+ "binding" => { "binding" => b, "signing_key" => "owner", "jti" => "urn:uuid:00000000-0000-4000-8000-#{Digest::SHA256.hexdigest("jti:#{name}")[0, 12]}", "iat" => iso(ENVELOPE_NOW - 60), "nonce" => Digest::SHA256.hexdigest("binding:#{name}")[0, 32] },
483
+ "policy_url" => "https://door.example/policy", "audience" => nil, "nonce" => Digest::SHA256.hexdigest(name)[0, 32] }
484
+ binding_jws = Signer.new(owner_key: o).sign(Binding.from_h(b), jti: inputs["binding"]["jti"], iat: ENVELOPE_NOW - 60, nonce: inputs["binding"]["nonce"])
485
+ env = Envelope.build(holder: k.did, mandate_jws: mandate_jws, record: record.fetch("block"), binding_jws: binding_jws, policy_url: inputs["policy_url"], nonce: inputs["nonce"], presented_at: ENVELOPE_NOW)
486
+ write(name, {
487
+ "name" => name,
488
+ "description" => "One consistent Agent Passport Envelope (spec v1.0) from the valid vectors: FlexYield's indicative mandate block (as delivered), FlexTrust's indicative record block (full tier, as delivered) and FlexHold's binding over that mandate for agent K with the record's ERC-8004 id. Built by `flexhold present` from a store holding the three; a door verifier should report every block ok, the cross-checks ok and `bound_stale` as the one advisory (record says bound:false, a live binding is presented).",
489
+ "spec" => "docs/bridge/ENVELOPE-SPEC-v1.0.md", "now" => iso(ENVELOPE_NOW), "inputs" => inputs.compact,
490
+ "verify" => {
491
+ "mandate" => { "jwk_directory" => mandate.fetch("jwk_directory") },
492
+ "record" => { "key_directory" => record.fetch("key_directory"), "commitments" => record.fetch("commitments") },
493
+ "binding" => { "status_list" => "status-list-valid", "registration" => "registration-snapshot", "mandate_bytes" => "the compact JWS in verifiableCredential[roles.mandate].id after data:application/vc+jwt,", "mandate_issuer" => claims["iss"], "request_key_id" => k.did }
494
+ },
495
+ "expected" => { "envelope" => env, "envelope_hash" => Envelope.hash(env), "blocks" => { "mandate" => "ok", "record" => "ok", "binding" => "ok" }, "cross" => [], "advisory" => [ "bound_stale" ],
496
+ "data_form_bytes" => Envelope.data_url(env).bytesize }
497
+ })
498
+ end
499
+
500
+ def binding(**over)
501
+ {
502
+ "owner" => o.did,
503
+ "agent" => { "key_id" => k.did },
504
+ "mandate" => { "hash" => "sha256:" + Digest::SHA256.hexdigest(MANDATE_BYTES), "issuer" => "did:web:flexyield.example", "version" => "1" },
505
+ "valid_from" => iso(Vectors::NOW - 60),
506
+ "valid_until" => iso(Vectors::NOW + 86_400),
507
+ "status" => { "url" => Vectors::STATUS_URL, "index" => 7, "issuer" => r.did },
508
+ "consent_ref" => "consent:2026-10-26:0001",
509
+ "identity_refs" => []
510
+ }.merge(over)
511
+ end
512
+
513
+ def erc_agent(id) = { "key_id" => k.did, "erc8004" => { "chain_id" => 1, "registry" => Vectors::REGISTRY, "agent_id" => id } }
514
+
515
+ def bindings
516
+ v = { "status_list" => "status-list-valid" }
517
+ {
518
+ "binding-valid" => { desc: "standing binding, all checks pass", verify: v, ok: true, reason: "ok" },
519
+ "binding-valid-all-checks" => { desc: "mandate bytes + mandate issuer (v1.1), request key and audience all supplied and matching", audience: "https://door.example/policy",
520
+ verify: v.merge("mandate_bytes_b64" => Base64.strict_encode64(MANDATE_BYTES), "mandate_issuer" => "did:web:flexyield.example", "request_key_id" => k.did, "audience" => "https://door.example/policy"), ok: true, reason: "ok" },
521
+ "binding-v1-type" => { desc: "a v1 binding: type without `AgentBinding` (signed before v1.1) still verifies — the two pinned types suffice", type: [ "VerifiableCredential", "FlexHoldBinding" ], verify: v, ok: true, reason: "ok" },
522
+ "binding-expired" => { desc: "verified after valid_until", now: Vectors::NOW + 2 * 86_400, verify: v, ok: false, reason: "expired" },
523
+ "binding-not-yet-valid" => { desc: "verified before valid_from", now: Vectors::NOW - 3600, verify: v, ok: false, reason: "not_yet_valid" },
524
+ "binding-revoked" => { desc: "status list has bit 7 set", verify: { "status_list" => "status-list-revoked" }, ok: false, reason: "revoked" },
525
+ "binding-status-unavailable" => { desc: "status list cannot be resolved", verify: {}, ok: false, reason: "status_unavailable" },
526
+ "binding-status-wrong-issuer" => { desc: "status list signed by a key the binding does not name", verify: { "status_list" => "status-list-wrong-issuer" }, ok: false, reason: "status_invalid" },
527
+ "binding-wrong-owner" => { desc: "claims name O as issuer but the signature is X's (the hijack case)", forged: true, verify: v, ok: false, reason: "signature_invalid" },
528
+ "binding-mandate-mismatch" => { desc: "presented mandate bytes hash to a different value", verify: v.merge("mandate_bytes_b64" => Base64.strict_encode64("other mandate")), ok: false, reason: "mandate_mismatch" },
529
+ "binding-mandate-issuer-mismatch" => { desc: "v1.1 rule 5: the bytes hash correctly but the mandate's issuer is not the one the binding names", verify: v.merge("mandate_bytes_b64" => Base64.strict_encode64(MANDATE_BYTES), "mandate_issuer" => "did:web:other.example"), ok: false, reason: "mandate_mismatch" },
530
+ "binding-agent-mismatch" => { desc: "the request was signed by a key other than K", verify: v.merge("request_key_id" => x.did), ok: false, reason: "agent_mismatch" },
531
+ "binding-audience-mismatch" => { desc: "door-bound binding presented at another door", audience: "https://door.example/policy", verify: v.merge("audience" => "https://other.example/policy"), ok: false, reason: "audience_mismatch" },
532
+ "binding-audience-missing" => { desc: "door-bound binding verified without an audience", audience: "https://door.example/policy", verify: v, ok: false, reason: "audience_mismatch" },
533
+ "binding-erc8004-valid" => { desc: "ERC-8004 agent 42 whose registration owner equals O", binding: { "agent" => erc_agent("42") }, verify: v.merge("registration" => "registration-snapshot"), ok: true, reason: "ok" },
534
+ "binding-erc8004-owner-mismatch" => { desc: "ERC-8004 agent 43 is registered to X, binding signed by O", binding: { "agent" => erc_agent("43") }, verify: v.merge("registration" => "registration-snapshot"), ok: false, reason: "owner_mismatch" },
535
+ "binding-erc8004-registration-unavailable" => { desc: "ERC-8004 agent, no registration snapshot supplied", binding: { "agent" => erc_agent("42") }, verify: v, ok: false, reason: "registration_unavailable" },
536
+ # did:pkh owners (EIP-712 profile, H1.1)
537
+ "binding-pkh-valid" => { desc: "wallet owner (did:pkh:eip155:1), EIP-712 signature, standing binding", key: "owner_pkh", verify: v, ok: true, reason: "ok" },
538
+ "binding-pkh-door-bound" => { desc: "wallet owner, door-bound binding presented at that door", key: "owner_pkh", audience: "https://door.example/policy", verify: v.merge("audience" => "https://door.example/policy"), ok: true, reason: "ok" },
539
+ "binding-pkh-wrong-owner" => { desc: "claims name wallet O, signature recovers to wallet X (the hijack case)", key: "owner_pkh", forged_by: "other_pkh", forged: true, verify: v, ok: false, reason: "signature_invalid" },
540
+ "binding-pkh-erc8004-valid" => { desc: "ERC-8004 agent 44 registered to wallet O, binding signed by wallet O", key: "owner_pkh", binding: { "agent" => erc_agent("44") }, verify: v.merge("registration" => "registration-snapshot"), ok: true, reason: "ok" }
541
+ }
542
+ end
543
+
544
+ def write_binding(name, spec)
545
+ signing_key = spec[:key] || "owner"
546
+ signer = Vectors.key(signing_key)
547
+ b = binding(**{ "owner" => signer.did }.merge(spec[:binding] || {}))
548
+ inputs = { "binding" => b, "signing_key" => signing_key, "jti" => "urn:uuid:00000000-0000-4000-8000-#{Digest::SHA256.hexdigest("jti:#{name}")[0, 12]}",
549
+ "iat" => iso(Vectors::NOW - 60), "nonce" => Digest::SHA256.hexdigest(name)[0, 32], "audience" => spec[:audience], "type" => spec[:type] }
550
+ jws = if spec[:type] # older type array, same claims otherwise (v1.1 compatibility vector)
551
+ claims = Binding.from_h(b).to_claims(jti: inputs["jti"], iat: Vectors::NOW - 60, nonce: inputs["nonce"], audience: spec[:audience])
552
+ JWS.sign(claims.merge("type" => spec[:type]), signer)
553
+ elsif spec[:forged]
554
+ forged_claims = Binding.from_h(b).to_claims(jti: inputs["jti"], iat: Vectors::NOW - 60, nonce: inputs["nonce"], audience: spec[:audience])
555
+ # X signs claims that name O: header kid is X's, iss/issuer are O's → signature_invalid against O
556
+ JWS.sign(forged_claims, Vectors.key(spec[:forged_by] || "other"))
557
+ else
558
+ Signer.new(owner_key: signer).sign(Binding.from_h(b), jti: inputs["jti"], iat: Vectors::NOW - 60, nonce: inputs["nonce"], audience: spec[:audience])
559
+ end
560
+ write(name, {
561
+ "name" => name, "description" => spec[:desc], "spec" => "docs/spec/binding-v1.md",
562
+ "now" => iso(spec[:now] || Vectors::NOW), "forged" => spec[:forged] || false,
563
+ "inputs" => inputs.compact, "verify" => spec[:verify], "expected" => { "ok" => spec[:ok], "reason" => spec[:reason], "jws" => jws }
564
+ })
565
+ end
566
+ end
567
+ end
568
+ end