unidpp 0.1.0

data/lib/unidpp/gs1.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Unidpp
+  # GS1 key arithmetic shared by the identifier parsers: application
+  # identifiers, element-string parsing (parenthesized and bracketed
+  # human-readable forms) and the GS1 mod-10 check digit (GTIN-13/GTIN-14,
+  # SSCC-18).
+  module Gs1
+    # Identity-relevant application identifiers (AI -> value shape).
+    #   "00" SSCC (18 digits)   "01" GTIN-14
+    #   "10" batch/lot (<= 20 GS1 AI charset)   "21" serial (<= 20 charset)
+    IDENTITY_AIS = {
+      "00" => /\A\d{18}\z/,
+      "01" => /\A\d{14}\z/,
+      "10" => /\A[\x21-\x22\x25-\x2F\x30-\x39\x3A-\x3F\x41-\x5A\x5F\x61-\x7A]{1,20}\z/,
+      "21" => /\A[\x21-\x22\x25-\x2F\x30-\x39\x3A-\x3F\x41-\x5A\x5F\x61-\x7A]{1,20}\z/,
+    }.freeze
+
+    # Application identifiers accepted in a Digital Link URI path.
+    DL_PATH_AIS = %w[00 01 10 21].freeze
+
+    module_function
+
+    # GS1 general specification check digit: from the rightmost digit of
+    # the base (excluding the check position), multiply alternately by 3
+    # and 1; the check digit completes the next multiple of ten.
+    #
+    # @param base [String, #to_s] digits without the check digit
+    # @return [Integer] the check digit
+    def check_digit(base)
+      digits = base.to_s.chars.map(&:to_i)
+      raise Error, "check digit base must be non-empty digits" if digits.empty?
+
+      sum = digits.reverse.each_with_index.sum do |d, i|
+        d * (i.even? ? 3 : 1)
+      end
+      (10 - (sum % 10)) % 10
+    end
+
+    # @param with_check [String] full code including trailing check digit
+    # @return [Boolean]
+    def valid_check_digit?(with_check)
+      s = with_check.to_s
+      return false unless /\A\d+\z/.match?(s)
+
+      check_digit(s[0...-1]) == s[-1].to_i
+    end
+
+    # Parses a human-readable element string, e.g.
+    #   (01)09506000134352(10)ABC-123(21)9876543
+    # or the bracketed form
+    #   [00]006141411234567890
+    #
+    # @param input [String]
+    # @return [Hash{String => String}] AI -> value, in encounter order
+    # @raise [Unidpp::Error] on malformed input
+    def parse_element_string(input)
+      opener = input.to_s.start_with?("[") ? "[" : "("
+      values = {}
+      scanner = StringScanner.new(input.to_s.strip)
+      until scanner.eos?
+        scanner.skip(/\s*/)
+        break if scanner.eos?
+
+        unless scanner.scan(/#{Regexp.escape(opener)}/)
+          raise Error, "malformed element string at #{scanner.pos}: #{input}"
+        end
+
+        ai = scanner.scan(/\d{2,4}/)
+        raise Error, "missing application identifier in #{input}" if ai.nil?
+
+        scanner.skip(/\]/) if opener == "["
+        scanner.skip(/\)/) if opener == "("
+        # value runs until the next opener or end of string
+        value = scanner.scan_until(/(?=#{Regexp.escape(opener)}|\z)/) || scanner.rest
+        value = value.sub(/\s+\z/, "")
+        raise Error, "empty value for AI (#{ai})" if value.empty?
+
+        values[ai] = value
+      end
+      values
+    end
+
+    # Validates AI values against the identity AI table, including the
+    # mod-10 check digits of SSCC (00) and GTIN (01).
+    #
+    # @param values [Hash{String => String}]
+    # @raise [Unidpp::Error] on an unsupported AI, bad shape or bad check
+    #   digit
+    def validate_identity_ais!(values)
+      values.each do |ai, value|
+        pattern = IDENTITY_AIS[ai]
+        raise Error, "unsupported identity AI (#{ai})" if pattern.nil?
+        raise Error, "invalid value for AI (#{ai}): #{value}" unless pattern.match?(value)
+      end
+      %w[00 01].each do |ai|
+        next unless (code = values[ai])
+
+        raise Error, "invalid check digit for AI (#{ai}): #{code}" unless valid_check_digit?(code)
+      end
+    end
+  end
+end

data/lib/unidpp/identifier.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Unidpp
+  # Scheme-agnostic product identifier (framework layer L0, invariant I1:
+  # one subject, one identity, never re-minted).
+  #
+  # Parses the identity carriers the framework must bridge:
+  # * GS1 Digital Link URIs — https://id.example.com/01/09506000134352/10/LOT/21/SER
+  # * GS1 human-readable element strings — (01)09506000134352(10)LOT(21)SER
+  # * ISO/IEC 15459-style unique identifiers — [00]006141411234567890 (SSCC)
+  # * GB/T 33993-style national carrier wrappers — an https URL whose path
+  #   embeds a GTIN-13/GTIN-14, with optional lot/serial query parameters
+  # * plain URNs, including urn:epc:id:sgtin/sscc forms
+  #
+  # The parsed model normalizes the GS1 components (gtin, lot, serial,
+  # sscc) and derives the identifier granularity (model / batch / item per
+  # the identity lattice: bare GTIN -> model, +lot -> batch, +serial or
+  # SSCC -> item).
+  #
+  # (De)serialization is generated by lutaml-model from the attribute +
+  # mapping declarations below — no hand-rolled to_h / from_h.
+  class ProductIdentifier < Lutaml::Model::Serializable
+    class ParseError < Unidpp::Error; end
+
+    SCHEMES = %w[gs1-dl gs1-element iso-15459 gbt-33993 urn other].freeze
+    GRANULARITIES = %w[model batch item].freeze
+
+    attribute :scheme, :string, values: SCHEMES, default: -> { "other" }
+    # Original carrier value exactly as encountered.
+    attribute :value, :string
+    attribute :granularity, :string, values: GRANULARITIES,
+                                      default: -> { "model" }
+    # Normalized GS1 components (nil when absent).
+    attribute :gtin, :string          # canonical GTIN-14
+    attribute :lot, :string           # AI (10)
+    attribute :serial, :string        # AI (21)
+    attribute :sscc, :string          # SSCC-18, ISO/IEC 15459 transport unit
+
+    json do
+      map "scheme", to: :scheme
+      map "value", to: :value
+      map "granularity", to: :granularity
+      map "gtin", to: :gtin, render_nil: false
+      map "lot", to: :lot, render_nil: false
+      map "serial", to: :serial, render_nil: false
+      map "sscc", to: :sscc, render_nil: false
+    end
+
+    yaml do
+      map "scheme", to: :scheme
+      map "value", to: :value
+      map "granularity", to: :granularity
+      map "gtin", to: :gtin, render_nil: false
+      map "lot", to: :lot, render_nil: false
+      map "serial", to: :serial, render_nil: false
+      map "sscc", to: :sscc, render_nil: false
+    end
+
+    # -- parsing ------------------------------------------------------------
+
+    # @param input [String] carrier value
+    # @return [ProductIdentifier]
+    # @raise [ParseError] when no parser claims the input
+    def self.parse(input)
+      s = input.to_s.strip
+      raise ParseError, "blank identifier" if s.empty?
+
+      if s.match?(/\Aurn:/i)
+        parse_urn(s)
+      elsif s.match?(/\Ahttps?:\/\//i)
+        parse_web_uri(s)
+      elsif s.match?(/\A[\(\[]\d{2,4}[\)\]]/)
+        parse_element_string(s)
+      else
+        raise ParseError, "unrecognized identifier syntax: #{s}"
+      end
+    end
+
+    # @param input [String] parenthesized / bracketed element string
+    def self.parse_element_string(input)
+      values = Gs1.parse_element_string(input)
+      Gs1.validate_identity_ais!(values)
+      if values["00"]
+        new(scheme: "iso-15459", value: input, sscc: values["00"],
+            granularity: "item")
+      elsif values["01"]
+        new(scheme: "gs1-element", value: input, gtin: values["01"],
+             lot: values["10"], serial: values["21"],
+             granularity: granularity_for(values["21"], values["10"]))
+      else
+        raise ParseError, "no identity AI (00/01) in #{input}"
+      end
+    end
+
+    # @param input [String] GS1 Digital Link or GB/T 33993-style URI
+    def self.parse_web_uri(input)
+      uri = URI.parse(input)
+      segments = uri.path.to_s.split("/").reject(&:empty?)
+      if dl_identity_pairs?(segments)
+        values = segments.each_slice(2).to_h
+        Gs1.validate_identity_ais!(values)
+        if values["00"]
+          new(scheme: "gs1-dl", value: input, sscc: values["00"],
+              granularity: "item")
+        else
+          new(scheme: "gs1-dl", value: input, gtin: values["01"],
+              lot: values["10"], serial: values["21"],
+              granularity: granularity_for(values["21"], values["10"]))
+        end
+      elsif (gtin = gbt33993_gtin(segments))
+        params = URI.decode_www_form(uri.query.to_s).to_h
+        new(scheme: "gbt-33993", value: input, gtin: gtin,
+            lot: params["lot"], serial: params["serial"],
+            granularity: granularity_for(params["serial"], params["lot"]))
+      else
+        raise ParseError, "unrecognized identifier URI: #{input}"
+      end
+    rescue URI::InvalidURIError => e
+      raise ParseError, "invalid identifier URI: #{e.message}"
+    end
+
+    # @param input [String] plain or EPC URN
+    def self.parse_urn(input)
+      urn = input.downcase
+      if urn.start_with?("urn:epc:id:sgtin:")
+        parse_sgtin_urn(input)
+      elsif urn.start_with?("urn:epc:id:sscc:")
+        parse_sscc_urn(input)
+      else
+        new(scheme: "urn", value: input)
+      end
+    end
+
+    # urn:epc:id:sgtin:<companyPrefix>.<itemRef>.<serial>
+    # prefix+itemRef total 12 digits (GTIN-13 base) or 13 digits (GTIN-14
+    # base with leading indicator digit).
+    def self.parse_sgtin_urn(input)
+      parts = input.split(":").last.split(".")
+      raise ParseError, "malformed sgtin URN: #{input}" unless parts.size == 3
+
+      prefix, item_ref, serial = parts
+      base = "#{prefix}#{item_ref}"
+      unless /\A\d{12,13}\z/.match?(base)
+        raise ParseError,
+              "sgtin company prefix + item ref must total 12 or 13 digits"
+      end
+
+      gtin14 = base.length == 13 ? base : "0#{base}"
+      new(scheme: "urn", value: input,
+          gtin: "#{gtin14}#{Gs1.check_digit(base)}",
+          serial: serial, granularity: "item")
+    end
+
+    # urn:epc:id:sscc:<companyPrefix>.<ssccDigits>
+    def self.parse_sscc_urn(input)
+      parts = input.split(":").last.split(".")
+      raise ParseError, "malformed sscc URN: #{input}" unless parts.size == 2
+
+      joined = parts.join
+      sscc =
+        if joined.length == 17
+          "#{joined}#{Gs1.check_digit(joined)}"
+        elsif joined.length == 18
+          joined
+        else
+          raise ParseError, "sscc URN must carry 17 or 18 digits: #{input}"
+        end
+      raise ParseError, "invalid SSCC check digit in #{input}" unless Gs1.valid_check_digit?(sscc)
+
+      new(scheme: "urn", value: input, sscc: sscc, granularity: "item")
+    end
+
+    # -- derived identity ----------------------------------------------------
+
+    # Canonical human-readable form. GS1-based schemes canonicalize to the
+    # element string in ascending AI order, so the same product expressed
+    # as Digital Link or element string yields the same canonical form.
+    #
+    # @return [String]
+    def canonical
+      case scheme
+      when "gs1-dl", "gs1-element"
+        %w[01 10 21].filter_map do |ai|
+          v = { "01" => gtin, "10" => lot, "21" => serial }[ai]
+          "(#{ai})#{v}" if v
+        end.join
+      when "iso-15459"
+        sscc ? "(00)#{sscc}" : value.to_s
+      else
+        value.to_s
+      end
+    end
+
+    # Stable identity key across representations: scheme-independent for
+    # GS1-keyed identifiers, scheme-qualified otherwise.
+    #
+    # @return [String]
+    def canonical_id
+      if gtin
+        "gtin:#{gtin}#{lot ? "/lot:#{lot}" : ''}#{serial ? "/ser:#{serial}" : ''}"
+      elsif sscc
+        "sscc:#{sscc}"
+      elsif scheme == "urn"
+        value.to_s
+      else
+        "#{scheme}:#{value}"
+      end
+    end
+
+    # Granularity predicates (model? / batch? / item?) are generated by
+    # lutaml-model from the granularity value enumeration.
+
+    # @return [Boolean] check digits valid for the carried GS1 keys
+    def valid_keys?
+      [gtin, sscc].compact.all? { |key| Gs1.valid_check_digit?(key) }
+    end
+
+    def to_s
+      canonical
+    end
+
+    private_class_method def self.granularity_for(serial, lot)
+      serial ? "item" : (lot ? "batch" : "model")
+    end
+
+    private_class_method def self.dl_identity_pairs?(segments)
+      return false unless segments.size.even? && segments.size >= 2
+
+      segments.each_slice(2).all? { |ai, _| Gs1::DL_PATH_AIS.include?(ai) }
+    end
+
+    private_class_method def self.gbt33993_gtin(segments)
+      segments.filter_map do |segment|
+        next unless /\A\d{13,14}\z/.match?(segment)
+
+        segment if Gs1.valid_check_digit?(segment)
+      end.first
+    end
+  end
+end

data/lib/unidpp/link.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+
+module Unidpp
+  # Temporal interval of a link's validity.
+  class LinkInterval < Lutaml::Model::Serializable
+    attribute :from, "Lutaml::Model::Type::DateTime"
+    attribute :until, "Lutaml::Model::Type::DateTime"
+
+    json do
+      map "from", to: :from, render_nil: false
+      map "until", to: :until, render_nil: false
+    end
+
+    yaml do
+      map "from", to: :from, render_nil: false
+      map "until", to: :until, render_nil: false
+    end
+
+    # @param t [Time, DateTime]
+    # @return [Boolean]
+    def covers?(t)
+      t = t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+      (!from || t >= from) && (!self.until || t < self.until)
+    end
+  end
+
+  # Typed relationship edge between passports (I5). Edge types carry
+  # different legal and lifecycle semantics:
+  #
+  #   association    R1 loose (compatibility, supply) — navigational only
+  #   derivation     R2 ancestral (split/mix/refine/remanufacture)
+  #   installation   R3 structural parent<->child, temporal (see below)
+  #   type-lineage   R4 type versioning, derived types, config vectors
+  #   profile-of     R5 lens<->core (not a passport-to-passport edge)
+  #   custody        R6 social/control edges, orthogonal to structure
+  #   membership     R7 group nodes (shipments, kits, recall sets)
+  #
+  # Installation is its own event class, not generic containment: an
+  # installed component is a different legal object from the standalone
+  # one (permanent alteration, pairing, lifecycle coupling, and
+  # bidirectional parent knowledge — with the disclosure hazard that
+  # creates, hence visibility classes and salted parent commitments:
+  # proof-of-binding without knowledge-of-parent, I12).
+  #
+  # (De)serialization is generated by lutaml-model from the attribute +
+  # mapping declarations below — no hand-rolled to_h / from_h.
+  class PassportLink < Lutaml::Model::Serializable
+    TYPES = %w[
+      association derivation installation type-lineage profile-of custody membership
+    ].freeze
+    DIRECTIONS = %w[upstream downstream undirected].freeze
+    BINDING_METHODS = %w[
+      none fastened soldered glued welded potted integrated keyed
+    ].freeze
+    RECOVERABILITY = %w[restorable harvestable destructive absorbing].freeze
+    PAIRINGS = %w[none firmware key module].freeze
+    VISIBILITIES = %w[public restricted blind escrowed].freeze
+    ESCROWS = %w[none trustee].freeze
+
+    attribute :link_type, :string, values: TYPES
+    attribute :direction, :string, values: DIRECTIONS,
+                                   default: -> { "downstream" }
+    attribute :child, ProductIdentifier
+    attribute :parent, ProductIdentifier
+    attribute :interval, LinkInterval
+    # Binding strength: how the child is held by the parent.
+    attribute :binding_method, :string, values: BINDING_METHODS,
+                                        default: -> { "none" }
+    # Recoverability spectrum determines identity continuity:
+    #   restorable   disassembly restores a marketable standalone object
+    #   harvestable  recovered but altered; continues with parent history
+    #   destructive  child ceases; flows to material passport (derivation)
+    #   absorbing    identity dissolves (paint, adhesive)
+    attribute :recoverability, :string, values: RECOVERABILITY
+    # Parent-scoped slot identity ("battery slot 1 of car X").
+    attribute :slot_id, :string
+    # Pairing / re-identification on install.
+    attribute :pairing, :string, values: PAIRINGS, default: -> { "none" }
+    # Permanent alterations performed by the installation.
+    attribute :alterations, :string, collection: true, default: -> { [] }
+    # Edge visibility class (I12): blind is the consumer-install default —
+    # a child->parent edge reveals where a thing is.
+    attribute :visibility, :string, values: VISIBILITIES,
+                                    default: -> { "public" }
+    attribute :escrow, :string, values: ESCROWS, default: -> { "none" }
+    attribute :audiences, :string, collection: true, default: -> { [] }
+    # Proof-of-binding (blind edges): salted commitment to the parent,
+    # stored in the child's log; verifiable without revealing the parent.
+    attribute :parent_commitment, :string
+    attribute :commitment_salt, :string
+
+    json do
+      map "link_type", to: :link_type
+      map "direction", to: :direction
+      map "child", to: :child, render_nil: false
+      map "parent", to: :parent, render_nil: false
+      map "interval", to: :interval, render_nil: false
+      map "binding_method", to: :binding_method
+      map "recoverability", to: :recoverability, render_nil: false
+      map "slot_id", to: :slot_id, render_nil: false
+      map "pairing", to: :pairing
+      map "alterations", to: :alterations, render_nil: false
+      map "visibility", to: :visibility
+      map "escrow", to: :escrow
+      map "audiences", to: :audiences, render_nil: false
+      map "parent_commitment", to: :parent_commitment, render_nil: false
+      map "commitment_salt", to: :commitment_salt, render_nil: false
+    end
+
+    yaml do
+      map "link_type", to: :link_type
+      map "direction", to: :direction
+      map "child", to: :child, render_nil: false
+      map "parent", to: :parent, render_nil: false
+      map "interval", to: :interval, render_nil: false
+      map "binding_method", to: :binding_method
+      map "recoverability", to: :recoverability, render_nil: false
+      map "slot_id", to: :slot_id, render_nil: false
+      map "pairing", to: :pairing
+      map "alterations", to: :alterations, render_nil: false
+      map "visibility", to: :visibility
+      map "escrow", to: :escrow
+      map "audiences", to: :audiences, render_nil: false
+      map "parent_commitment", to: :parent_commitment, render_nil: false
+      map "commitment_salt", to: :commitment_salt, render_nil: false
+    end
+
+    # -- construction ---------------------------------------------------------
+
+    # Builds an installation edge (R3) with the full binding schema. When
+    # +visibility+ is blind (the consumer-install default), the parent is
+    # replaced by a salted commitment: the child proves it is validly
+    # installed in *some* parent without revealing which. The salt is the
+    # disclosure key (escrowed or revealed at ceremony).
+    #
+    # @return [PassportLink]
+    def self.install(child:, parent:, visibility: "blind",
+                     salt: SecureRandom.hex(16), **attrs)
+      link = new(link_type: "installation", direction: "downstream",
+                 child: child, parent: parent, visibility: visibility,
+                 **attrs)
+      if visibility == "blind"
+        link.parent = nil
+        link.parent_commitment = PassportLink.parent_commitment(child,
+                                                                parent, salt)
+        link.commitment_salt = salt
+      end
+      link
+    end
+
+    # @return [String] hex SHA-256 over the canonical child and parent
+    #   identities and the salt
+    def self.parent_commitment(child, parent, salt)
+      Digest::SHA256.hexdigest(
+        [child.canonical, parent.canonical, salt].join("\n")
+      )
+    end
+
+    # -- queries --------------------------------------------------------------
+
+    # Edge-type and visibility predicates (installation? / blind? /
+    # escrowed?) are generated by lutaml-model from the corresponding
+    # value enumerations.
+
+    def hidden_parent?
+      blind? && parent.nil? && !parent_commitment.nil?
+    end
+
+    # Does disassembly of this installation restore a marketable object
+    # with identity continuity? (R3 vs R2 boundary.)
+    def identity_continuity?
+      %w[restorable harvestable].include?(recoverability)
+    end
+
+    # Proof-of-binding check. For visible edges this is identity equality;
+    # for blind edges the candidate parent is recomputed against the
+    # stored salted commitment — full disclosure by ceremony only.
+    #
+    # @param candidate [ProductIdentifier] the parent being tested
+    # @return [Boolean]
+    def proves_parent?(candidate)
+      return false if candidate.nil?
+
+      if parent
+        parent.canonical == candidate.canonical
+      elsif parent_commitment
+        PassportLink.parent_commitment(child, candidate,
+                                       commitment_salt) == parent_commitment
+      else
+        false
+      end
+    end
+  end
+end