unidpp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36b87e3059f33a1fcf05f11132a11b1a41e93712fd0646d676734368a51b1776
+  data.tar.gz: 358c874dd088c697f3dc34a794c9ddf45b3d91221c91f6a170c2bfe254665bbf
+SHA512:
+  metadata.gz: 56bb1ff2a61e4049c007a76e8ba15fc31f6f549c11011e208adcbfea8801c86c2ac9d8963e3b19378e074d62cd0cf07d5078a08b5a67bdd29171b58d50234ff2
+  data.tar.gz: 9e9cd4772a9cdf050ee4944059eb6933784a1ba97971c9d07cfe5e35261a3d813933eea8d77c967fb74738897b085709c54bfbd843205516271d4b2ab4577c50

data/lib/unidpp/annexb.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Unidpp
+  # The Annex B binary canonical encoding (TODO 237), written from the
+  # specification: the framing rule (each field a little-endian u32
+  # length prefix and its bytes, in the declared field order), the
+  # domain tags, and the per-object derivations. The vendored golden
+  # vectors carry the reference `canonical_hex` pins; the suite
+  # asserts byte identity — this implementation agrees with the
+  # reference or the suite fails. That is the cross-implementation
+  # contract.
+  module AnnexB
+    module_function
+
+    SEGMENT_COMMITMENT = "UNIDPP-GRID/SEGMENT-COMMITMENT"
+    SPINE_LEAF = "UNIDPP-GRID/SPINE-LEAF"
+    SPINE_NODE = "UNIDPP-GRID/SPINE-NODE"
+    SPINE_DIGEST = "UNIDPP-GRID/SPINE-DIGEST"
+
+    REVEAL_TOKENS = {
+      "Open" => "open",
+      "PairingGated" => "pairing-gated",
+      "OriginSealed" => "origin-sealed",
+      "Escrowed" => "escrowed"
+    }.freeze
+
+    CLAIM_TOKENS = {
+      "conformity" => "conformity",
+      "commitment-hash" => "commitment-hash",
+      "freshness" => "freshness"
+    }.freeze
+
+    EVIDENCE_TOKENS = {
+      "verified-direct" => "verified-direct",
+      "attested-by-authority" => "attested-by-authority",
+      "explicitly-unavailable" => "explicitly-unavailable"
+    }.freeze
+
+    LEVEL_ORDINALS = {
+      "l0" => 0, "l1" => 1, "l2" => 2, "l3" => 3, "l4" => 4, "l5" => 5
+    }.freeze
+
+    def sha256(data)
+      Digest::SHA256.digest(data)
+    end
+
+    def le_u32(value)
+      [value].pack("V")
+    end
+
+    def le_u64(value)
+      [value].pack("Q<")
+    end
+
+    def part(bytes)
+      # UTF-8 strings keep their bytes (relabelled, never transcoded):
+      # the canonical bytes ARE the UTF-8 encoding, and the framing
+      # layer works in binary throughout.
+      binary = if bytes.is_a?(String)
+                 bytes.dup.force_encoding(Encoding::BINARY)
+               else
+                 bytes.pack("C*")
+               end
+      le_u32(binary.bytesize) + binary
+    end
+
+    # The canonical form: fields in declared order, each
+    # length-prefixed.
+    def canonical_fields(parts)
+      parts.map { |p| part(p) }.join
+    end
+
+    # The one framing rule: tag || 0x00 || payload.
+    def domain_frame(tag, payload)
+      tag + "\x00".b + payload
+    end
+
+    # Hash in a domain: sha256 over the domain-framed canonical parts.
+    def hash_in(domain, parts)
+      sha256(domain_frame(domain, canonical_fields(parts)))
+    end
+
+    # Wire forms carry hashes either hex-encoded or as byte arrays.
+    def as_bytes(value)
+      value.is_a?(String) ? [value].pack("H*") : value.pack("C*")
+    end
+
+    # A sorted, deduplicated list joined with the unit separator
+    # (U+001F).
+    def canon_list(values)
+      values.uniq.sort.join("\x1f")
+    end
+
+    def policy_canonical(policy)
+      parts = [
+        policy["policy_id"],
+        le_u64(policy["version"]),
+        policy["authority"],
+        REVEAL_TOKENS.fetch(policy["reveal"], policy["reveal"]),
+        policy["valid_from"],
+        canon_list(policy["readers"]),
+        canon_list(policy["verifiers"]),
+        canon_list(policy["writers"]),
+        canon_list(policy["suites"])
+      ]
+      parts << policy["valid_to"] unless policy["valid_to"].nil?
+      parts << le_u64(policy["superseded_by"]) unless policy["superseded_by"].nil?
+      canonical_fields(parts)
+    end
+
+    def h_pair(left, right)
+      a, b = [left, right].minmax
+      hash_in(SPINE_NODE, [a, b])
+    end
+
+    def commit_state(state)
+      hash_in(SEGMENT_COMMITMENT, [state])
+    end
+
+    def spine_root(commitments)
+      level = commitments.keys.sort.map do |id|
+        hash_in(SPINE_LEAF, [id, as_bytes(commitments[id])])
+      end
+      return "\x00".b * 32 if level.empty?
+
+      while level.size > 1
+        level = level.each_slice(2).map do |pair|
+          pair.size == 2 ? h_pair(pair[0], pair[1]) : h_pair(pair[0], pair[0])
+        end
+      end
+      level.first
+    end
+
+    def spine_digest(version, commitments)
+      buf = le_u64(version) + spine_root(commitments)
+      commitments.keys.sort.each do |id|
+        buf += le_u32(id.bytesize) + id + as_bytes(commitments[id])
+      end
+      hash_in(SPINE_DIGEST, [buf])
+    end
+
+    def request_canonical(request)
+      canonical_fields(
+        [
+          request["verifier"],
+          request["subject"],
+          request["profile"],
+          request["segment"],
+          request["at"]
+        ]
+      )
+    end
+
+    def response_canonical(response)
+      outcome = response["outcome"]
+      payload = outcome.reject { |k, _| k == "outcome" }
+      canonical_fields(
+        [
+          as_bytes(response["request_digest"]),
+          outcome["outcome"],
+          *payload.values,
+          response["governing_policy"],
+          le_u64(response["governing_policy_version"]),
+          response["custodian"]
+        ]
+      )
+    end
+
+    def route_canonical(route)
+      parts = [le_u64(route["steps"].size)]
+      route["steps"].each do |step|
+        kind = step["step"]
+        parts << kind
+        case kind
+        when "resolve" then parts << step["subject"]
+        when "transport" then parts << step["mode"] << step["counterpart"]
+        when "document" then parts << step["kind"] << as_bytes(step["digest"])
+        when "substitution" then parts << step["data_class"] << step["service"]
+        when "classify"
+          e = step["entry"]
+          parts << e["class"] << e["element_set"] <<
+            EVIDENCE_TOKENS.fetch(e["evidence"], e["evidence"]) <<
+            e["governing_policy"] << le_u64(e["governing_policy_version"]) <<
+            e["reading"] << e["as_of"]
+        when "gap" then parts << step["data_class"] << step["reason"]
+        end
+      end
+      canonical_fields(parts)
+    end
+
+    def route_digest(route)
+      sha256(route_canonical(route))
+    end
+
+    def report_canonical(report)
+      parts = [
+        report["subject"],
+        report["profile"],
+        report["verified_at"],
+        le_u64(report["route"] ? 1 : 0)
+      ]
+      parts << route_digest(report["route"]) if report["route"]
+      parts << le_u64(report["entries"].size)
+      report["entries"].each do |e|
+        parts << e["class"] << e["element_set"] <<
+          EVIDENCE_TOKENS.fetch(e["evidence"], e["evidence"]) <<
+          e["governing_policy"] << le_u64(e["governing_policy_version"]) <<
+          e["reading"] << e["as_of"]
+      end
+      canonical_fields(parts)
+    end
+
+    def statement_canonical(statement)
+      canonical_fields(
+        [
+          statement["segment"],
+          as_bytes(statement["state_commitment"]),
+          CLAIM_TOKENS.fetch(statement["claim"], statement["claim"]),
+          statement["value"],
+          statement["as_of"],
+          statement["governing_policy"],
+          le_u64(statement["governing_policy_version"]),
+          statement["subject"]
+        ]
+      )
+    end
+
+    def descriptor_token(descriptor)
+      [descriptor["temporal"], descriptor["content"], descriptor["derivation"],
+       descriptor["exchange"], descriptor["granularity"]].join("·")
+    end
+
+    def frozen_view_canonical(view)
+      parts = [
+        view["subject"],
+        descriptor_token(view["descriptor"]),
+        view["lens"]["profile"]
+      ]
+      view["lens"]["transforms"].each do |step|
+        parts << step["reference"] << le_u64(step["version"])
+      end
+      view["lens"]["input_segments"].each do |name, segment|
+        parts << name << segment
+      end
+      parts << as_bytes(view["payload"])
+      view["inputs"].each do |input|
+        parts << input["name"] << commit_state(as_bytes(input["bytes"]))
+      end
+      view["instructions"].each { |instruction| parts << instruction }
+      parts << view["notarized_at"]
+      parts << spine_digest(view["bundle"]["spine"]["spine"]["version"],
+                            view["bundle"]["spine"]["spine"]["commitments"])
+      canonical_fields(parts)
+    end
+
+    def declaration_canonical(declaration)
+      postures = declaration["postures"].sort_by { |p| p["data_class"] }
+      parts = [
+        declaration["declarer"],
+        declaration["counterpart"],
+        le_u64(declaration["version"])
+      ]
+      postures.each do |posture|
+        parts << posture["data_class"]
+        parts << [LEVEL_ORDINALS.fetch(posture["level"], 255)].pack("C")
+        parts << posture["recognition"]
+        posture["transports"].sort.each { |transport| parts << transport }
+        parts << (posture["escalation"] || "")
+        parts << (posture["reciprocity"] || "")
+      end
+      parts << declaration["valid_from"]
+      parts << (declaration["valid_to"] || "")
+      canonical_fields(parts)
+    end
+
+    def mapping_item_canonical(item)
+      parts = [item["source"], item["target"], le_u64(item["version"])]
+      kind = item["kind"]
+      case kind["tier"]
+      when "deterministic"
+        parts << "tier-1" << kind["transform"]
+      when "correspondence"
+        parts << "tier-2"
+        kind["scope"].sort.each { |scope| parts << scope }
+        parts << kind["residual"] << kind["attester"]
+      when "no-mapping"
+        parts << "tier-3" << kind["note"]
+      else
+        raise ArgumentError, "unknown mapping tier `#{kind['tier']}'"
+      end
+      canonical_fields(parts)
+    end
+  end
+end

data/lib/unidpp/canonical_json.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Unidpp
+  # Deterministic canonical JSON used for commitments (event-log chaining,
+  # blind-edge parent commitments).
+  #
+  # The source document is always the *framework-generated* serialization
+  # of a Lutaml::Model object (to_json); this module only imposes a
+  # canonical key order on top of that output so that identical logical
+  # documents always hash identically, regardless of hash insertion order.
+  # It is a canonicalizer, not a serializer: no model mappings live here.
+  module CanonicalJson
+    module_function
+
+    # @param serializable [Lutaml::Model::Serializable]
+    # @return [String] canonical JSON with all object keys sorted
+    #   (recursively).
+    def of(serializable)
+      sorted(JSON.parse(serializable.to_json)).to_json
+    end
+
+    # @param obj [Object] parsed JSON structure
+    # @return [Object] same structure with every Hash's keys sorted
+    def sorted(obj)
+      case obj
+      when Hash
+        obj.keys.sort.to_h { |k| [k, sorted(obj[k])] }
+      when Array
+        obj.map { |v| sorted(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/unidpp/event.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Unidpp
+  # Typed lifecycle event (I4: append-only event sourcing; the event log
+  # is the authoritative record). The post-first-sale taxonomy E1–E15
+  # with the roles authorized to append each kind — nothing is ever
+  # edited in place; every change is an appended event.
+  class Event < Lutaml::Model::Serializable
+    # event type -> roles that may append it (the appender column of the
+    # taxonomy; "any" means any custodian-role actor per profile rules).
+    TAXONOMY = {
+      "custody.transfer"    => %w[custodian counterparty],
+      "part.replace"        => %w[repairer],
+      "repair.perform"      => %w[repairer],
+      "product.modify"      => %w[modifier],
+      "software.update"     => %w[eo service],
+      "feature.unlock"      => %w[eo service],
+      "upgrade.install"     => %w[installer],
+      "refurbish.perform"   => %w[refurbisher],
+      "consumable.replace"  => %w[custodian repairer eo service installer],
+      "recall.campaign"     => %w[regulator eo],
+      "correction.record"   => %w[eo manufacturer certifier],
+      "status.change"       => %w[regulator eo],
+      "flag.security"       => %w[authority registrar],
+      "decompose.perform"   => %w[recycler transformer],
+      "inspection.stamp"    => %w[verifier certifier],
+      "milestone.record"    => %w[device custodian],
+    }.freeze
+
+    EVENT_TYPES = TAXONOMY.keys.freeze
+
+    ACTOR_ROLES = TAXONOMY.values.flatten.uniq.freeze
+
+    # Graded trust markers (I9 / source invariant 8: trust is graded, not
+    # mandated — every event carries one).
+    TRUST_MARKERS = %w[
+      unsigned self_declared third_party_attested multi_signed log_anchored
+    ].freeze
+
+    class UnauthorizedAppenderError < Unidpp::Error; end
+
+    # event_id has deliberately NO default: the log assigns it exactly
+    # once at append, so the committed canonical form is stable whether
+    # the event was hand-built or round-tripped.
+    attribute :event_id, :string
+    attribute :event_type, :string, values: EVENT_TYPES
+    attribute :occurred_at, "Lutaml::Model::Type::DateTime"
+    attribute :actor, :string               # named actor
+    attribute :actor_role, :string, values: ACTOR_ROLES
+    # Canonical identity of the subject whose log this event appends to.
+    attribute :subject, :string
+    # Free event payload (string-keyed, scalar values); canonicalized by
+    # the event log for commitments.
+    attribute :payload, :hash, default: -> { {} }
+    attribute :trust_marker, :string, values: TRUST_MARKERS,
+                                      default: -> { "unsigned" }
+
+    # Defaulted attributes render always (render_default: true) so that
+    # the canonical JSON hashed into commitments does not depend on
+    # whether the value was explicitly assigned or materialized.
+    json do
+      map "event_id", to: :event_id
+      map "event_type", to: :event_type
+      map "occurred_at", to: :occurred_at
+      map "actor", to: :actor, render_nil: false
+      map "actor_role", to: :actor_role
+      map "subject", to: :subject
+      map "payload", to: :payload, render_default: true
+      map "trust_marker", to: :trust_marker, render_default: true
+    end
+
+    yaml do
+      map "event_id", to: :event_id
+      map "event_type", to: :event_type
+      map "occurred_at", to: :occurred_at
+      map "actor", to: :actor, render_nil: false
+      map "actor_role", to: :actor_role
+      map "subject", to: :subject
+      map "payload", to: :payload, render_default: true
+      map "trust_marker", to: :trust_marker, render_default: true
+    end
+
+    # Appender authorization: the actor role must be among the roles the
+    # taxonomy allows for this event kind (I4 discipline — custody
+    # transfer is appended by the custodian, a recall by the regulator,
+    # and so on).
+    #
+    # @return [Boolean]
+    def authorized_appender?
+      TAXONOMY.fetch(event_type, []).include?(actor_role)
+    end
+
+    # @raise [UnauthorizedAppenderError]
+    def authorize_appender!
+      unless authorized_appender?
+        raise UnauthorizedAppenderError,
+              "#{actor_role} may not append #{event_type}"
+      end
+    end
+  end
+end

data/lib/unidpp/event_log.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+
+module Unidpp
+  # Append-only, hash-chained event log with salted commitments (I4, S6).
+  #
+  # Chain rule: each entry's commitment is
+  #
+  #   SHA-256( canonical_json(event) || salt || previous_commitment )
+  #
+  # where canonical_json is the framework (lutaml-model) serialization of
+  # the event under a deterministic key order. The salt disciplines the
+  # log↔transparency-log seam: logs anchor commitments, never facts — a
+  # reveal (event + salt) must remain inclusion-consistent with every
+  # past commitment ("commit now, reveal later, never contradict").
+  class EventLog
+    class IntegrityError < Unidpp::Error; end
+
+    # The commitment envelope of one event. (De)serialization is generated
+    # by lutaml-model — no hand-rolled to_h / from_h.
+    class Entry < Lutaml::Model::Serializable
+      attribute :event, Event
+      attribute :salt, :string           # hex — the disclosure key
+      attribute :previous, :string       # hex commitment of prior entry
+      attribute :commitment, :string     # hex commitment of this entry
+
+      json do
+        map "event", to: :event
+        map "salt", to: :salt
+        map "previous", to: :previous
+        map "commitment", to: :commitment
+      end
+
+      yaml do
+        map "event", to: :event
+        map "salt", to: :salt
+        map "previous", to: :previous
+        map "commitment", to: :commitment
+      end
+    end
+
+    # Serialized form of a whole log. (De)serialization is generated by
+    # lutaml-model — no hand-rolled to_h / from_h.
+    class Document < Lutaml::Model::Serializable
+      attribute :subject, :string
+      attribute :algorithm, :string, default: -> { "sha256" }
+      attribute :entries, Entry, collection: true, default: -> { [] }
+
+      json do
+        map "subject", to: :subject
+        map "algorithm", to: :algorithm
+        map "entries", to: :entries
+      end
+
+      yaml do
+        map "subject", to: :subject
+        map "algorithm", to: :algorithm
+        map "entries", to: :entries
+      end
+    end
+
+    # Commitment of the empty log (genesis value of the chain).
+    GENESIS = "0" * 64
+    ALGORITHM = "sha256"
+
+    attr_reader :document
+
+    def initialize(subject:, entries: [])
+      @document = Document.new(subject: subject, algorithm: ALGORITHM,
+                               entries: entries)
+      @document.entries.freeze
+    end
+
+    # -- append-only writer ---------------------------------------------------
+
+    # Appends +event+ with a fresh salt, chaining onto the current head.
+    # The event's id is assigned here exactly once (if the caller did not
+    # set one) so the committed canonical form is stable; existing
+    # entries are never touched.
+    #
+    # @param event [Event]
+    # @param salt [String] disclosure key (generated when omitted)
+    # @return [Entry]
+    def append(event, salt: SecureRandom.hex(16))
+      event.event_id ||= SecureRandom.uuid
+      entry = Entry.new(event: event, salt: salt, previous: head,
+                        commitment: nil)
+      entry.commitment = commitment_for(entry.event, entry.salt,
+                                        entry.previous)
+      new_entries = @document.entries + [entry]
+      @document = Document.new(subject: @document.subject,
+                               algorithm: @document.algorithm,
+                               entries: new_entries)
+      @document.entries.freeze
+      entry
+    end
+
+    # -- queries ---------------------------------------------------------------
+
+    # @return [Array<Entry>]
+    def entries
+      @document.entries
+    end
+
+    def events
+      entries.map(&:event)
+    end
+
+    def empty?
+      entries.empty?
+    end
+
+    # Head commitment: the value a transparency log anchors.
+    #
+    # @return [String] hex
+    def head
+      entries.last&.commitment || GENESIS
+    end
+    alias commitment head
+
+    def subject
+      @document.subject
+    end
+
+    # Notarized as-of state: the contiguous sub-log of events that had
+    # occurred at +t+. The sub-chain re-verifies because chaining is
+    # prefix-consistent.
+    #
+    # @param t [Time, DateTime]
+    # @return [EventLog]
+    def as_of(t)
+      t = t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+      EventLog.new(subject: subject,
+                   entries: entries.select do |e|
+                     !e.event.occurred_at.nil? && e.event.occurred_at <= t
+                   end)
+    end
+
+    # The reveal pair for an entry — the material a counterparty needs to
+    # check inclusion-consistency of a past commitment.
+    #
+    # @param event_id [String]
+    # @return [Entry, nil]
+    def reveal(event_id)
+      entries.find { |e| e.event.event_id == event_id }
+    end
+
+    # -- integrity ---------------------------------------------------------------
+
+    # @return [Array<String>] human-readable integrity problems, [] when
+    #   the chain is sound
+    def integrity_errors
+      errors = []
+      previous = GENESIS
+      entries.each_with_index do |entry, index|
+        if entry.previous != previous
+          errors << "entry #{index} (#{entry.event.event_type}): " \
+                    "previous #{entry.previous.inspect} != #{previous.inspect}"
+        end
+        expected = commitment_for(entry.event, entry.salt, entry.previous)
+        if entry.commitment != expected
+          errors << "entry #{index} (#{entry.event.event_type}): " \
+                    "commitment does not cover the stored event+salt"
+        end
+        previous = entry.commitment
+      end
+      errors
+    end
+
+    # @return [Boolean]
+    def valid?
+      integrity_errors.empty?
+    end
+
+    # @raise [IntegrityError] on the first problem found
+    def verify!
+      errors = integrity_errors
+      return self if errors.empty?
+
+      raise IntegrityError, errors.first
+    end
+
+    # Inclusion-consistency of a reveal: recomputing the commitment from
+    # the revealed event and salt must reproduce the anchored commitment.
+    #
+    # @param entry [Entry]
+    # @return [Boolean]
+    def consistent_reveal?(entry)
+      entry.commitment == commitment_for(entry.event, entry.salt,
+                                         entry.previous)
+    end
+
+    # -- framework serialization -------------------------------------------------
+
+    def self.from_yaml(yaml)
+      document = Document.from_yaml(yaml)
+      new(subject: document.subject, entries: document.entries)
+    end
+
+    def self.from_json(json)
+      document = Document.from_json(json)
+      new(subject: document.subject, entries: document.entries)
+    end
+
+    def to_yaml
+      @document.to_yaml
+    end
+
+    def to_json(*_args)
+      @document.to_json
+    end
+
+    private
+
+    # SHA-256 over the canonical JSON of the event, the salt and the
+    # previous commitment.
+    def commitment_for(event, salt, previous)
+      Digest::SHA256.hexdigest(
+        [CanonicalJson.of(event), salt, previous].join("\n")
+      )
+    end
+  end
+end