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,101 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ # H3 · present_passport: one envelope per door from the owner's store. Minimum disclosure by ROLE (ENVELOPE §5): the roles come
5
+ # from the door's published gate policy (H3.2, `policy:` — a Policy the service layer read at policy_url or from a handed-in
6
+ # document) or are named by the caller (H3.1, `roles:` — the caller's word wins); `also:` adds roles on top of the policy (the
7
+ # mandate is never implied by a policy key). Nothing but the selected blocks leaves the store, and the consent log records to
8
+ # whom, what (ids + hash), why (policy source + hash, never its text) and when. The presenter never dials out.
9
+ module Presenter
10
+ SELECTABLE = %w[mandate record binding].freeze
11
+ IDENTITY = "identity" # H2.3: the array role — only on explicit ask, never from a policy; the selected binding's identity_refs say which
12
+ ROLES = (SELECTABLE + [ IDENTITY ]).freeze
13
+
14
+ module_function
15
+
16
+ # agent: the agent key K (did:key / Web Bot Auth key id) the envelope is presented by — items are K's when they name K or the
17
+ # ERC-8004 id K's binding carries. roles: nil = from the policy, else every role present; an explicit role with no live item refuses.
18
+ def present(store:, agent:, roles: nil, policy: nil, also: nil, policy_url: nil, audience: nil, agent_key_path: nil, nonce: SecureRandom.hex(16), now: Time.now)
19
+ raise Malformed, "agent must be a DID or key id" unless agent.is_a?(String) && !agent.strip.empty?
20
+ raise Malformed, "policy must be a FlexHold::Policy" unless policy.nil? || policy.is_a?(Policy)
21
+
22
+ wanted, roles_from = wanted_roles(roles, policy, also)
23
+ policy_url ||= policy.source if policy&.url?
24
+
25
+ chosen = select(store, agent, wanted)
26
+ identity = Array(chosen[IDENTITY])
27
+ env = Envelope.build(holder: agent, nonce: nonce, presented_at: now, policy_url: policy_url, audience: audience,
28
+ mandate_jws: chosen["mandate"] && block_jws(chosen["mandate"]),
29
+ record: chosen["record"]&.dig("payload", "block"),
30
+ binding_jws: chosen["binding"]&.dig("payload", "jws"),
31
+ identity: identity.map { |i| block_jws(i) })
32
+ env = Envelope.sign(env, Keys.from_pem(agent_key_path)) if agent_key_path
33
+
34
+ ids = SELECTABLE.filter_map { |r| chosen[r] && chosen[r]["id"] } + identity.map { |i| i["id"] }
35
+ present_roles = SELECTABLE.select { |r| chosen[r] } + (identity.any? ? [ IDENTITY ] : [])
36
+ hash = Envelope.hash(env)
37
+ id = "presentation:#{SecureRandom.uuid}"
38
+ detail = { "to" => policy_url || audience, "roles" => present_roles, "roles_from" => roles_from, "items" => ids, "envelope_hash" => hash, "nonce" => nonce,
39
+ "policy" => policy && { "source" => policy.source, "hash" => policy.hash, "fields" => policy.keys } }.compact
40
+ entry = store.note(event: "presented", subject: id, now: now, detail: detail)
41
+ { "presentation_id" => id, "envelope" => env, "envelope_hash" => hash, "roles" => present_roles, "items" => ids,
42
+ "agent_passport" => Envelope.data_url(env, strict: false), "bytes" => Envelope.canonical(env).bytesize, "log_seq" => entry["seq"],
43
+ "policy" => policy&.to_h }.compact
44
+ end
45
+
46
+ # roles named → exactly those (+ also); a policy → its roles (+ also); neither → every role present. → [wanted or nil, provenance]
47
+ def wanted_roles(roles, policy, also)
48
+ named = roles.nil? ? nil : Array(roles).map(&:to_s)
49
+ extra = Array(also).map(&:to_s)
50
+ (named.to_a + extra).each { |r| raise Malformed, "unknown role #{r.inspect} (roles: #{ROLES.join(', ')})" unless ROLES.include?(r) }
51
+ if named then [ ROLES & (named + extra), "explicit" ]
52
+ elsif policy then [ ROLES & (policy.roles + extra), extra.empty? ? "policy" : "policy+also" ]
53
+ elsif extra.any? then [ ROLES & extra, "explicit" ]
54
+ else [ nil, "all" ] # every single role present; identity credentials only on explicit ask
55
+ end
56
+ end
57
+
58
+ # The newest live item per role. K's bindings (live or withdrawn — the link is a fact about K, consent is per item) tell which
59
+ # ERC-8004 id is K's, so a record issued to that id is K's as well.
60
+ def select(store, agent, wanted)
61
+ all = store.items
62
+ live = all.reject { |i| i["withdrawn_at"] }
63
+ ids = ([ agent ] + all.select { |i| i["kind"] == "binding" && Array(i["agents"]).include?(agent) }.flat_map { |i| Array(i["agents"]) }).uniq
64
+ binding = newest(live.select { |i| i["kind"] == "binding" && Array(i["agents"]).include?(agent) })
65
+ chosen = SELECTABLE.to_h do |role|
66
+ [ role, role == "binding" ? binding : newest(live.select { |i| i["kind"] == role && (Array(i["agents"]) & ids).any? }) ]
67
+ end
68
+ chosen[IDENTITY] = identity_items(live, binding, agent) if wanted&.include?(IDENTITY)
69
+ missing = ((wanted || SELECTABLE) - [ IDENTITY ]).reject { |r| chosen[r] }
70
+ raise PresentationRefused.new(:role_unavailable, "no live #{missing.join(', ')} block for #{agent} in this store") if wanted ? missing.any? : missing.size == SELECTABLE.size
71
+
72
+ wanted ? chosen.slice(*wanted) : chosen
73
+ end
74
+
75
+ # H2.3 · the identity credentials K's live binding references (`identity_refs` = credential ids), in the binding's order, live only.
76
+ # The binding is the owner's statement of which credentials belong here; without it, or with none live, there is nothing to present.
77
+ def identity_items(live, binding, agent)
78
+ raise PresentationRefused.new(:role_unavailable, "identity asked, but no live binding for #{agent} names identity credentials") unless binding
79
+
80
+ refs = Array(JWS.decode(binding.dig("payload", "jws")).last.dig("credentialSubject", "identity_refs"))
81
+ raise PresentationRefused.new(:role_unavailable, "identity asked, but the binding for #{agent} references no identity credential (pseudonymous owner)") if refs.empty?
82
+
83
+ by_id = live.select { |i| i["kind"] == IDENTITY }.group_by { |i| i.dig("payload", "verification", "block", "id") }
84
+ items = refs.filter_map { |ref| by_id[ref] && newest(by_id[ref]) }
85
+ raise PresentationRefused.new(:role_unavailable, "identity asked, but none of the credentials the binding references is live in this store (#{refs.join(', ')})") if items.empty?
86
+
87
+ items
88
+ end
89
+
90
+ def newest(items) = items.max_by { |i| [ i["added_at"].to_s, i["id"] ] }
91
+
92
+ # A stored JWS-secured block (mandate, identity): the compact JWS, bytes as collected.
93
+ def block_jws(item)
94
+ block = item.dig("payload", "block")
95
+ jws = block.is_a?(Hash) ? block["jws"] : block
96
+ raise Malformed, "stored #{item['kind']} item #{item['id']} carries no compact JWS" unless jws.is_a?(String)
97
+
98
+ jws.strip
99
+ end
100
+ end
101
+ end
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "stringio"
4
+
5
+ module FlexHold
6
+ # Injectable lookups so any verifier can plug its own sources (build instructions §4: "any RPC or any signed snapshot").
7
+ module Resolvers
8
+ # url → status-list JWS from an in-memory map (tests, vectors).
9
+ class StaticStatus
10
+ def initialize(map) = @map = map
11
+ def call(url) = @map.fetch(url) { raise StatusUnavailable, "no status list for #{url}" }
12
+ end
13
+
14
+ # file:///path or a plain path → status-list JWS. The only network-free source in H1; hosting is a later decision.
15
+ class FileStatus
16
+ def call(url)
17
+ raise StatusUnavailable, "only file:// status lists are supported in H1" unless url.is_a?(String) && (url.start_with?("file://") || url.start_with?("/"))
18
+
19
+ File.read(url.delete_prefix("file://")).strip
20
+ rescue SystemCallError
21
+ raise StatusUnavailable, "status list not readable"
22
+ end
23
+ end
24
+
25
+ # "eip155:<chain_id>:<registry>:<agent_id>" → owner DID, from an in-memory map.
26
+ # A signed registration snapshot (any source, FlexTrust's nightly root among them) feeds this map; the
27
+ # snapshot's own signature check is the caller's (H2+).
28
+ class StaticRegistration
29
+ def self.key_for(erc) = "eip155:#{erc['chain_id']}:#{erc['registry'].downcase}:#{erc['agent_id']}"
30
+
31
+ def initialize(map) = @map = map
32
+ def call(erc) = @map[self.class.key_for(erc)]
33
+ end
34
+
35
+ # JSON snapshot file: { "registrations": [ { "chain_id": 1, "registry": "0x…", "agent_id": "42", "owner": "did:…" }, … ] }
36
+ class FileRegistration < StaticRegistration
37
+ def initialize(path)
38
+ data = JSON.parse(File.read(path))
39
+ map = Array(data["registrations"]).to_h { |r| [ StaticRegistration.key_for(r), r["owner"] ] }
40
+ super(map)
41
+ rescue SystemCallError, JSON::ParserError, TypeError
42
+ raise Malformed, "registration snapshot not readable"
43
+ end
44
+ end
45
+ end
46
+ end
47
+
48
+ module FlexHold
49
+ module Resolvers
50
+ # One status-list JWS for whatever URL the binding names (CLI --status FILE, MCP status_list_path).
51
+ class FixedStatus
52
+ def initialize(jws) = @jws = jws
53
+ def call(_url) = @jws
54
+ end
55
+ end
56
+ end
@@ -0,0 +1,48 @@
1
+ # frozen_string_literal: true
2
+
3
+ # guarded — ADR-003 (revocation without key O: the recovery key R re-issues the status list, ADR-004)
4
+ module FlexHold
5
+ # Owns a status-list file: init, revoke (set a bit, re-issue, atomic write, mode 0600).
6
+ class Revoker
7
+ DEFAULT_VALID_FOR = 86_400 # the refresh window a verifier tolerates before it must fetch again
8
+
9
+ def self.init(recovery_key:, url:, path:, now: Time.now, valid_for: DEFAULT_VALID_FOR)
10
+ raise Error, "recovery key must be a private key" unless recovery_key.private?
11
+
12
+ write_atomically(path, StatusList::Credential.issue(issuer_key: recovery_key, url: url, valid_from: now, valid_for: valid_for))
13
+ end
14
+
15
+ def self.write_atomically(path, content)
16
+ tmp = "#{path}.tmp#{SecureRandom.hex(4)}"
17
+ File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |f| f.write(content) }
18
+ File.rename(tmp, path)
19
+ path
20
+ ensure
21
+ File.delete(tmp) if tmp && File.exist?(tmp)
22
+ end
23
+
24
+ def initialize(recovery_key:, path:, now: Time.now, valid_for: DEFAULT_VALID_FOR)
25
+ raise Error, "recovery key must be a private key" unless recovery_key.private?
26
+
27
+ @recovery_key, @path, @now, @valid_for = recovery_key, path, now, valid_for
28
+ end
29
+
30
+ def revoke(index)
31
+ self.class.write_atomically(@path, current.with_revoked(index, issuer_key: @recovery_key, valid_from: @now, valid_for: @valid_for))
32
+ end
33
+
34
+ # Re-issue the same list with a fresh validity window (the holder's refresh duty; an expired list is still revocable).
35
+ def refresh
36
+ c = current
37
+ self.class.write_atomically(@path, StatusList::Credential.issue(issuer_key: @recovery_key, url: c.url, valid_from: @now, valid_for: @valid_for, bitstring: c.bitstring))
38
+ end
39
+
40
+ private
41
+
42
+ def current
43
+ StatusList::Credential.parse(File.read(@path).strip, expected_issuer: @recovery_key.did, now: @now, allow_expired: true)
44
+ rescue StatusInvalid, SystemCallError => e
45
+ raise Error, "cannot re-issue: #{e.message}"
46
+ end
47
+ end
48
+ end
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+
3
+ # guarded — ADR-003 / ADR-005: ECDSA over secp256k1 with RFC 6979 deterministic nonces and public-key recovery,
4
+ # on Ruby's OpenSSL big-number and EC-point arithmetic (no native secp256k1 library). Pinned by the EIP-712
5
+ # specification example in test/secp256k1_eip712_test.rb.
6
+ require "digest/keccak"
7
+
8
+ module FlexHold
9
+ module Secp256k1
10
+ GROUP = OpenSSL::PKey::EC::Group.new("secp256k1")
11
+ G = GROUP.generator
12
+ N = GROUP.order
13
+ P = OpenSSL::BN.new("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F", 16)
14
+ HALF_N = N >> 1
15
+ SIG_BYTES = 65
16
+
17
+ module_function
18
+
19
+ def keccak256(bytes) = Digest::Keccak.digest(bytes, 256)
20
+
21
+ def bn(bytes) = OpenSSL::BN.new(bytes.unpack1("H*"), 16)
22
+ def octets(bn, len = 32) = bn.to_s(2).rjust(len, "\x00").b
23
+
24
+ def public_key(private_bytes)
25
+ d = bn(private_bytes)
26
+ raise Malformed, "private key out of range" unless d > 0 && d < N
27
+
28
+ G.mul(d).to_octet_string(:uncompressed) # 0x04 || X || Y
29
+ end
30
+
31
+ # EIP-55 checksummed address of an uncompressed public key.
32
+ def address(public_uncompressed) = checksum(keccak256(public_uncompressed.byteslice(1, 64)).byteslice(12, 20).unpack1("H*"))
33
+
34
+ def checksum(address)
35
+ raw = address.delete_prefix("0x").downcase
36
+ raise Malformed, "not an EVM address" unless raw.match?(/\A[0-9a-f]{40}\z/)
37
+
38
+ hash = keccak256(raw).unpack1("H*")
39
+ "0x" + raw.each_char.with_index.map { |c, i| hash[i].to_i(16) >= 8 ? c.upcase : c }.join
40
+ end
41
+
42
+ # digest (32 bytes) → r || s || v (v = 27 + recovery id), low-s, RFC 6979 nonce.
43
+ def sign(digest, private_bytes)
44
+ raise Malformed, "digest must be 32 bytes" unless digest.bytesize == 32
45
+
46
+ d = bn(private_bytes)
47
+ z = bn(digest)
48
+ rfc6979_nonces(private_bytes, digest) do |k|
49
+ r_point = G.mul(k)
50
+ xy = r_point.to_octet_string(:uncompressed)
51
+ r = bn(xy.byteslice(1, 32)) % N
52
+ next if r.zero?
53
+
54
+ s = k.mod_inverse(N).mod_mul(z.mod_add(r.mod_mul(d, N), N), N)
55
+ next if s.zero?
56
+
57
+ rec = xy.getbyte(64) & 1
58
+ if s > HALF_N
59
+ s = N - s
60
+ rec ^= 1
61
+ end
62
+ return octets(r) + octets(s) + (27 + rec).chr
63
+ end
64
+ end
65
+
66
+ def recover_address(digest, signature)
67
+ raise SignatureInvalid, "signature must be #{SIG_BYTES} bytes" unless signature.is_a?(String) && signature.bytesize == SIG_BYTES
68
+ raise SignatureInvalid, "digest must be 32 bytes" unless digest.bytesize == 32
69
+
70
+ r, s, v = bn(signature.byteslice(0, 32)), bn(signature.byteslice(32, 32)), signature.getbyte(64)
71
+ raise SignatureInvalid, "v must be 27 or 28" unless [ 27, 28 ].include?(v)
72
+ raise SignatureInvalid, "r out of range" unless r > 0 && r < N
73
+ raise SignatureInvalid, "s must be low-s" unless s > 0 && s <= HALF_N
74
+
75
+ rec = v - 27
76
+ # R = (x, y) with x = r and y of the parity rec; y² = x³ + 7 (mod p), p ≡ 3 (mod 4) → y = (x³+7)^((p+1)/4)
77
+ y2 = r.mod_exp(3, P).mod_add(7, P)
78
+ y = y2.mod_exp((P + 1) >> 2, P)
79
+ raise SignatureInvalid, "r is not an x-coordinate on the curve" unless y.mod_sqr(P) == y2
80
+
81
+ y = P - y if (y % 2).to_i != rec
82
+ r_point = OpenSSL::PKey::EC::Point.new(GROUP, OpenSSL::BN.new("04" + octets(r).unpack1("H*") + octets(y).unpack1("H*"), 16))
83
+ z = bn(digest)
84
+ r_inv = r.mod_inverse(N)
85
+ # Q = r⁻¹ (s·R − z·G)
86
+ neg_zg = G.mul((N - (z % N)) % N)
87
+ q = r_point.mul(s).add(neg_zg).mul(r_inv)
88
+ raise SignatureInvalid, "recovered point at infinity" if q.infinity?
89
+
90
+ address(q.to_octet_string(:uncompressed))
91
+ rescue OpenSSL::PKey::EC::Point::Error, OpenSSL::BNError
92
+ raise SignatureInvalid, "signature does not recover"
93
+ end
94
+
95
+ # RFC 6979 §3.2 with HMAC-SHA256 (q = N, 256-bit hash). Yields candidate nonces until the block returns.
96
+ def rfc6979_nonces(private_bytes, digest)
97
+ hmac = ->(key, data) { OpenSSL::HMAC.digest("SHA256", key, data) }
98
+ x = private_bytes
99
+ h1 = octets(bn(digest) % N) # bits2octets
100
+ v = ("\x01" * 32).b
101
+ k = ("\x00" * 32).b
102
+ k = hmac.(k, v + "\x00".b + x + h1)
103
+ v = hmac.(k, v)
104
+ k = hmac.(k, v + "\x01".b + x + h1)
105
+ v = hmac.(k, v)
106
+ loop do
107
+ v = hmac.(k, v)
108
+ candidate = bn(v)
109
+ yield candidate if candidate > 0 && candidate < N
110
+ k = hmac.(k, v + "\x00".b)
111
+ v = hmac.(k, v)
112
+ end
113
+ end
114
+ end
115
+ end
@@ -0,0 +1,231 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FlexHold
4
+ # The one place the CLI and the MCP tools call (same service objects, one source of truth). Inputs are paths and
5
+ # JSON; outputs are plain hashes. Private key material is read from files and never returned.
6
+ module Services
7
+ module_function
8
+
9
+ def keygen(out:, type: "ed25519", chain_id: 1)
10
+ raise Error, "refusing to overwrite #{out}" if File.exist?(out)
11
+
12
+ key = case type
13
+ when "ed25519" then Keys::Ed25519.generate
14
+ when "secp256k1" then Keys::Secp256k1.generate(chain_id: Integer(chain_id))
15
+ else raise Malformed, "type must be ed25519 or secp256k1"
16
+ end
17
+ key.write_pem(out)
18
+ { "did" => key.did, "kid" => key.kid, "alg" => key.alg, "path" => out }
19
+ end
20
+
21
+ def sign(key_path:, binding:, audience: nil, out: nil, chain_id: 1)
22
+ key = Keys.from_pem(key_path, chain_id: Integer(chain_id))
23
+ binding = JSON.parse(File.read(binding)) if binding.is_a?(String) && File.exist?(binding)
24
+ binding = JSON.parse(binding) if binding.is_a?(String)
25
+ jws = Signer.new(owner_key: key).sign(Binding.from_h(binding), audience: audience)
26
+ File.write(out, jws + "\n") if out
27
+ { "jws" => jws, "owner" => key.did, "out" => out }
28
+ end
29
+
30
+ def verify(jws:, status: nil, mandate: nil, mandate_issuer: nil, registration: nil, request_key_id: nil, audience: nil, now: Time.now)
31
+ jws = File.read(jws).strip if File.exist?(jws.to_s)
32
+ status_resolver = status ? Resolvers::FixedStatus.new(File.read(status).strip) : Resolvers::FileStatus.new
33
+ registration_resolver = registration && Resolvers::FileRegistration.new(registration)
34
+ mandate_bytes = mandate && File.binread(mandate)
35
+ Verifier.new(status_resolver: status_resolver, registration_resolver: registration_resolver, now: -> { now })
36
+ .verify(jws, mandate_bytes: mandate_bytes, mandate_issuer: mandate_issuer, request_key_id: request_key_id, audience: audience).to_h
37
+ end
38
+
39
+ def status_list_init(recovery_key_path:, url:, out:, valid_for: Revoker::DEFAULT_VALID_FOR)
40
+ raise Error, "refusing to overwrite #{out}" if File.exist?(out)
41
+
42
+ key = Keys::Ed25519.from_pem(recovery_key_path)
43
+ Revoker.init(recovery_key: key, url: url, path: out, valid_for: valid_for)
44
+ { "url" => url, "issuer" => key.did, "path" => out }
45
+ end
46
+
47
+ def status_list_refresh(recovery_key_path:, path:, valid_for: Revoker::DEFAULT_VALID_FOR)
48
+ key = Keys::Ed25519.from_pem(recovery_key_path)
49
+ Revoker.new(recovery_key: key, path: path, valid_for: valid_for).refresh
50
+ { "path" => path, "issuer" => key.did, "refreshed" => true }
51
+ end
52
+
53
+ def revoke(recovery_key_path:, status_list:, index:, valid_for: Revoker::DEFAULT_VALID_FOR)
54
+ key = Keys::Ed25519.from_pem(recovery_key_path)
55
+ Revoker.new(recovery_key: key, path: status_list, valid_for: valid_for).revoke(Integer(index))
56
+ { "path" => status_list, "index" => Integer(index), "revoked" => true, "issuer" => key.did }
57
+ rescue ArgumentError, TypeError
58
+ raise Malformed, "index must be an integer"
59
+ end
60
+
61
+ def vectors_verify(dir: Vectors::DEFAULT_DIR)
62
+ bindings = Vectors::Runner.new(dir).run
63
+ records = Vectors::RecordRunner.new(dir).run + Vectors::MandateRunner.new(dir).run + Vectors::IdentityRunner.new(dir).run
64
+ results = bindings.map { |o| { "name" => o.name, "ok" => o.ok?, "expected" => o.expected, "actual" => o.actual, "signature_reproduced" => o.signature_ok } } +
65
+ records.map { |o| { "name" => o.name, "ok" => o.ok?, "expected" => o.expected, "actual" => o.actual } }
66
+ results += Vectors::EnvelopeRunner.new(dir).run.map { |o| { "name" => o.name, "ok" => o.ok?, "expected" => "rebuilt + blocks ok", "actual" => o.actual, "rebuilt" => o.rebuilt, "blocks" => o.blocks } }
67
+ { "ok" => results.all? { |r| r["ok"] }, "count" => results.size, "results" => results }
68
+ end
69
+
70
+ # H2 · the collector. keys / commitments: a file or an https URL; none = an empty source (nothing is trusted by default).
71
+ def record_verify(path:, keys: nil, commitments: nil, now: nil, fetcher: Collector::Fetcher::HTTPS.new)
72
+ raw, _location = Collector::Sources::FlexTrustRecord.fetch(path, fetcher: Collector::Fetcher::Static.new({}))
73
+ t = time_or_now(now)
74
+ Collector::RecordVerifier.new(key_directory: Collector::KeyDirectory.load(keys, fetcher: fetcher),
75
+ commitments: Collector::Commitments.load(commitments, fetcher: fetcher), now: -> { t }).verify(raw).to_h
76
+ end
77
+
78
+ # ref: agent id | passport URL | file. For a remote ref the FlexTrust sources default to the live documents (zero cost:
79
+ # public tier, well-known, commitments); for a file nothing is fetched unless asked.
80
+ def record_collect(ref:, keys: nil, commitments: nil, out: nil, now: nil, fetcher: Collector::Fetcher::HTTPS.new)
81
+ src = Collector::Sources::FlexTrustRecord
82
+ if src.remote?(ref)
83
+ keys ||= src::KEYS_URL
84
+ commitments ||= src::COMMITMENTS_URL
85
+ end
86
+ t = time_or_now(now)
87
+ collected = Collector.collect(source: src::NAME, ref: ref, fetcher: fetcher, now: -> { t },
88
+ key_directory: Collector::KeyDirectory.load(keys, fetcher: fetcher),
89
+ commitments: Collector::Commitments.load(commitments, fetcher: fetcher))
90
+ File.write(out, JSON.pretty_generate(collected) + "\n") if out
91
+ collected.merge("out" => out)
92
+ end
93
+
94
+ # H2.2 · the FlexYield mandate block. keys = a JWK Set with validity (file or https URL); none = nothing trusted.
95
+ # agent = the agent key K the owner's binding names, checked against the mandate's subject.
96
+ def mandate_verify(path:, keys: nil, now: nil, agent: nil, fetcher: Collector::Fetcher::HTTPS.new)
97
+ raw, _location = Collector::Sources::FlexYieldMandate.fetch(path, fetcher: Collector::Fetcher::Static.new({}))
98
+ t = time_or_now(now)
99
+ Collector::MandateVerifier.new(jwk_directory: Collector::JwkDirectory.load(keys, fetcher: fetcher), now: -> { t }, expected_agent: agent).verify(raw).to_h
100
+ end
101
+
102
+ def mandate_collect(ref:, keys: nil, out: nil, now: nil, agent: nil, fetcher: Collector::Fetcher::HTTPS.new)
103
+ src = Collector::Sources::FlexYieldMandate
104
+ keys ||= src::KEYS_URL if src.remote?(ref)
105
+ t = time_or_now(now)
106
+ collected = Collector.collect(source: src::NAME, ref: ref, fetcher: fetcher, now: -> { t }, expected_agent: agent,
107
+ key_directory: Collector::JwkDirectory.load(keys, fetcher: fetcher))
108
+ File.write(out, JSON.pretty_generate(collected) + "\n") if out
109
+ collected.merge("out" => out)
110
+ end
111
+
112
+ # H2.3 · an owner-identity credential (jwt_vc_json) from any issuer. keys = the ISSUER's JWK Set with validity (file or https URL;
113
+ # required in practice — nothing is trusted without it, and there is no default URL because the issuer is a third party).
114
+ # status = the issuer's status-list JWS as a file (else file:// URLs in credentialStatus resolve, https ones read status_unavailable).
115
+ # owner = the owner DID O the binding names; the credential's subject must be O.
116
+ def identity_verify(path:, keys: nil, status: nil, now: nil, owner: nil, fetcher: Collector::Fetcher::HTTPS.new)
117
+ raw, _location = Collector::Sources::Identity.fetch(path, fetcher: Collector::Fetcher::Static.new({}))
118
+ t = time_or_now(now)
119
+ Collector::IdentityVerifier.new(jwk_directory: Collector::JwkDirectory.load(keys, fetcher: fetcher), status_resolver: status_resolver(status),
120
+ now: -> { t }, expected_owner: owner).verify(raw).to_h
121
+ end
122
+
123
+ def identity_collect(ref:, keys: nil, status: nil, out: nil, now: nil, owner: nil, fetcher: Collector::Fetcher::HTTPS.new)
124
+ t = time_or_now(now)
125
+ collected = Collector.collect(source: Collector::Sources::Identity::NAME, ref: ref, fetcher: fetcher, now: -> { t }, expected_owner: owner,
126
+ key_directory: Collector::JwkDirectory.load(keys, fetcher: fetcher), status_resolver: status_resolver(status))
127
+ File.write(out, JSON.pretty_generate(collected) + "\n") if out
128
+ collected.merge("out" => out)
129
+ end
130
+
131
+ def status_resolver(status) = status ? Resolvers::FixedStatus.new(File.read(status).strip) : Resolvers::FileStatus.new
132
+
133
+ # H4 · the owner's store. The passphrase comes from a 0600 file or FLEXHOLD_STORE_PASSPHRASE — never from argv or a tool argument.
134
+ PASSPHRASE_ENV = "FLEXHOLD_STORE_PASSPHRASE"
135
+
136
+ def passphrase(file = nil)
137
+ value = if file
138
+ File.read(file).chomp
139
+ else
140
+ ENV.fetch(PASSPHRASE_ENV, nil)
141
+ end
142
+ raise Malformed, "no store passphrase: set #{PASSPHRASE_ENV} or pass --passphrase-file" if value.nil? || value.empty?
143
+
144
+ value
145
+ rescue SystemCallError
146
+ raise Malformed, "passphrase file not readable"
147
+ end
148
+
149
+ def store_init(store:, owner:, passphrase_file: nil, now: Time.now)
150
+ s = Store.create(store, owner: owner, passphrase: passphrase(passphrase_file), now: now)
151
+ { "store" => store, "store_id" => s.store_id, "owner" => s.owner, "created_at" => s.created_at }
152
+ end
153
+
154
+ def store_add(store:, path:, passphrase_file: nil, now: Time.now)
155
+ raise Malformed, "not readable: #{path}" unless File.file?(path.to_s)
156
+
157
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
158
+ item = s.add(File.read(path), now: now)
159
+ item.reject { |k, _| k == "payload" }.merge("payload" => (item["kind"] == "binding" ? { "status_list_path" => item.dig("payload", "status_list_path") } : nil)).compact.merge("store_id" => s.store_id)
160
+ end
161
+
162
+ def store_list(store:, passphrase_file: nil)
163
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
164
+ { "store_id" => s.store_id, "owner" => s.owner, "items" => s.items.map { |i| i.reject { |k, _| k == "payload" } } }
165
+ end
166
+
167
+ def store_show(store:, id:, passphrase_file: nil)
168
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
169
+ s.item(id) || raise(Malformed, "no item #{id}")
170
+ end
171
+
172
+ def store_export(store:, out:, passphrase_file: nil, now: Time.now)
173
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
174
+ bundle = s.export(now: now)
175
+ Revoker.write_atomically(out, JSON.generate(bundle))
176
+ { "out" => out, "store_id" => s.store_id, "items" => s.items.size, "log_entries" => bundle["consent_log"].size }
177
+ end
178
+
179
+ def store_import(bundle:, store:, passphrase_file: nil, now: Time.now)
180
+ s = Store.import(bundle, store, passphrase: passphrase(passphrase_file), now: now)
181
+ { "store" => store, "store_id" => s.store_id, "owner" => s.owner, "items" => s.items.size }
182
+ end
183
+
184
+ def consent_log(store:)
185
+ v = ConsentLog.new(File.join(store, Store::LOG_FILE)).verify
186
+ { "ok" => v["ok"], "count" => v["count"], "head" => v["head"], "broken_at" => v["broken_at"], "entries" => v["entries"] }
187
+ end
188
+
189
+ def consent_withdraw(store:, recovery_key_path:, item: nil, agent: nil, reason: nil, passphrase_file: nil, now: Time.now)
190
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
191
+ Consent.withdraw(store: s, recovery_key_path: recovery_key_path, item: item, agent: agent, reason: reason, now: now)
192
+ end
193
+
194
+ # H3 · present_passport: one envelope for one door from the store (roles = minimum disclosure). H3.2: the roles come from the
195
+ # door's policy — `policy` (file or https URL, read first) or, without explicit `roles`, fetched at `policy_url`; `also` adds roles
196
+ # (the mandate only on ask); explicit `roles` win and skip the read. Nothing named = every role present (H3.1).
197
+ # out: write the document (file form); the result carries the data form (`agent_passport`) when the envelope fits 32 KB.
198
+ def present(store:, agent:, roles: nil, policy: nil, also: nil, policy_url: nil, audience: nil, agent_key_path: nil, out: nil, passphrase_file: nil,
199
+ now: Time.now, fetcher: Policy.default_fetcher)
200
+ roles = list(roles)
201
+ also = list(also)
202
+ policy = policy_for(policy, roles.nil? ? policy_url : nil, fetcher)
203
+ s = Store.open(store, passphrase: passphrase(passphrase_file))
204
+ r = Presenter.present(store: s, agent: agent, roles: roles, policy: policy, also: also, policy_url: policy_url, audience: audience, agent_key_path: agent_key_path, now: now)
205
+ Revoker.write_atomically(out, JSON.pretty_generate(r["envelope"]) + "\n") if out
206
+ r.merge("out" => out).compact
207
+ end
208
+
209
+ # H3.2 · policy read: a door's policy (file or https URL) → the roles the presenter would disclose. Pure read, no store.
210
+ def policy_read(source:, fetcher: Policy.default_fetcher) = Policy.load(source, fetcher: fetcher).to_h
211
+
212
+ def policy_for(policy, policy_url, fetcher)
213
+ return policy if policy.is_a?(Policy)
214
+ return Policy.load(policy, fetcher: fetcher) if policy
215
+
216
+ policy_url && Policy.fetch(policy_url, fetcher: fetcher)
217
+ end
218
+
219
+ def list(v)
220
+ return v.split(",").map(&:strip).reject(&:empty?) if v.is_a?(String)
221
+
222
+ v.nil? ? nil : Array(v).map(&:to_s)
223
+ end
224
+
225
+ def time_or_now(v)
226
+ v.nil? ? Time.now : Time.iso8601(v.to_s)
227
+ rescue ArgumentError
228
+ raise Malformed, "now must be an RFC 3339 timestamp"
229
+ end
230
+ end
231
+ end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ # guarded — ADR-003 (the one signature FlexHold makes; changes need Christian's permission + second confirmation)
4
+ module FlexHold
5
+ # Signs a Binding with the owner's key O → compact JWS (typ vc+jwt, alg EdDSA).
6
+ # The key object is the owner's; nothing here persists or prints private material.
7
+ class Signer
8
+ def initialize(owner_key:)
9
+ raise Error, "owner key must be a private key" unless owner_key.private?
10
+
11
+ @owner_key = owner_key
12
+ end
13
+
14
+ def sign(binding, audience: nil, jti: "urn:uuid:#{SecureRandom.uuid}", iat: Time.now, nonce: SecureRandom.hex(16))
15
+ raise Error, "binding.owner (#{binding.owner}) is not this key (#{@owner_key.did})" unless binding.owner == @owner_key.did
16
+
17
+ JWS.sign(binding.to_claims(jti: jti, iat: iat, nonce: nonce, audience: audience), @owner_key)
18
+ end
19
+ end
20
+ end