open-presence 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 481b794cc29eb5471b718099609816afa6e3fd6451fe6c4371f553a98719824f
+  data.tar.gz: 26ae208bdf34b8ff671a7148a4ec4c623df0b42151e73671436bac76eae9d803
+SHA512:
+  metadata.gz: 3d0c520725e9b454b4428d9d7bdb1d8a87fe8b2f5da916efe6ab472f35f8a9a8b738b5dacc4c37a4995067842c0df32394c2247b2ed4e5f9fcc7eff84de9bb54
+  data.tar.gz: ca394a17f97cc5e6cc2a16d17fc67dc62aa557605eac4c2d8cd341310331fc097d9d715ef0d9808fed6651b538f6a30a11ba1455bea487c2301a0b096f138e97

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,146 @@
+# OPP Ruby
+
+`opp` implements the Open Presence Protocol (OPP) 0.1 Presence Document
+lifecycle and reusable OPP signing primitives for Ruby 3.2 and newer.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "open-presence", "~> 0.1.0"
+```
+
+Then run `bundle install`. To install it directly, run
+`gem install opp -v "~> 0.1.0"`.
+
+## Presence Documents
+
+Generate an Ed25519 key pair and derive its OPP subject:
+
+```ruby
+require "opp"
+require "time"
+
+pair = OPP::KeyPair.generate
+subject = OPP::Subject.derive(pair.public_key)
+```
+
+`pair.private_key` is a secret 32-byte seed encoded as unpadded Base64url.
+Do not log, publish, or commit it. Store it with the same protections as any
+other signing credential. The public key and derived subject are safe to
+publish.
+
+Sign a Presence Document. Signing returns a new hash and does not mutate the
+input. The public key, subject, and signature are added by the library.
+
+```ruby
+document = {
+  "type" => "open-presence",
+  "version" => "0.1",
+  "issued_at" => "2026-07-12T00:00:00Z",
+  "expires_at" => "2026-07-13T00:00:00Z",
+  "services" => [
+    { "type" => "profile", "url" => "https://example.com/alice" }
+  ]
+}
+
+signed = OPP::Presence.sign(document, private_key: pair.private_key)
+```
+
+Non-bang verification returns an `OPP::VerificationResult`. Pass `at:` when
+you need a reproducible verification time; otherwise it defaults to the
+current UTC time.
+
+```ruby
+result = OPP::Presence.verify(
+  signed,
+  at: Time.iso8601("2026-07-12T12:00:00Z")
+)
+
+if result.valid?
+  puts "valid"
+else
+  result.errors.each do |error|
+    warn [error.code, error.path, error.message].compact.join(": ")
+  end
+end
+```
+
+`OPP::Presence.verify!` returns `true` for a valid document and raises the
+first structured `OPP::Error` for an invalid one:
+
+```ruby
+begin
+  OPP::Presence.verify!(signed, at: Time.iso8601("2026-07-12T12:00:00Z"))
+rescue OPP::Error => error
+  warn "#{error.code} at #{error.path}: #{error.message}"
+end
+```
+
+Errors expose a machine-readable `code`, an optional field `path`, and a
+human-readable message. Specific failures use subclasses such as
+`OPP::ValidationError`, `OPP::InvalidSignatureError`,
+`OPP::ExpiredDocumentError`, and `OPP::UnsupportedVersionError`.
+
+Unknown top-level fields, unknown service fields, and unknown service types
+are accepted. They remain part of the canonical signed payload, so changing
+or removing them invalidates the signature.
+
+## Generic signatures
+
+`OPP::Signature` signs any JSON-object-shaped hash without applying Presence
+validation. This is useful for other OPP objects:
+
+```ruby
+registration = {
+  "type" => "open-presence-directory-registration",
+  "version" => "0.2",
+  "sequence" => 7,
+  "subject" => subject,
+  "extension" => { "enabled" => true }
+}
+
+signed_registration = OPP::Signature.sign(
+  registration,
+  private_key: pair.private_key
+)
+OPP::Signature.verify!(signed_registration, public_key: pair.public_key)
+```
+
+`OPP::Signature.verify!` returns `true` or raises
+`OPP::InvalidSignatureError`. `OPP::Signature.verify` is also available when
+a boolean result is preferable. Both signing APIs return deep copies rather
+than mutating caller-owned hashes, and unknown and nested fields are
+authenticated.
+
+The generic API is responsible only for signature structure,
+canonicalization, key handling, and cryptographic verification. In
+particular, it does not validate Directory Registration schemas, sequence
+rules, persistence, networking, or discovery. Applications using generic
+signatures must validate their own object schema and protocol rules.
+
+## Vectors and interoperability
+
+The offline conformance suite vendors the language-neutral OPP vectors under
+`spec/fixtures/opp`. Their source repository, exact commit, retrieval date,
+and verification time are recorded in `spec/fixtures/opp/UPSTREAM.yml`; the
+current snapshot comes from `jodydawkins/opp` commit
+`73e4e761ad05ac5b6f4cd7ac3ad7c59842dadeba`.
+
+For reciprocal interoperability testing:
+
+1. Use the deterministic private-key seed from the pinned vector snapshot.
+2. Sign the same document with `OPP::Presence.sign` and serialize the returned
+   hash as JSON.
+3. Add the Ruby-produced JSON to the upstream/Rust interoperability fixtures
+   and verify it there at the manifest's fixed verification time.
+4. Copy the corresponding Rust-produced signed fixture into the pinned Ruby
+   snapshot and run `bundle exec rspec spec/opp/conformance_spec.rb` offline.
+
+This gem deliberately has no CLI. Use the Ruby API directly or build
+application-specific commands around it.
+
+## License
+
+Apache-2.0. See `LICENSE`.

data/lib/opp/base64_url.rb

@@ -0,0 +1,27 @@
+require "base64"
+
+module OPP
+  module Base64URL
+    ALPHABET = /\A[A-Za-z0-9_-]*\z/
+
+    module_function
+
+    def encode(bytes)
+      Base64.urlsafe_encode64(bytes, padding: false)
+    end
+
+    def decode(value, length: nil)
+      unless value.is_a?(String) && ALPHABET.match?(value)
+        raise InvalidEncodingError, "invalid unpadded Base64url"
+      end
+
+      bytes = Base64.urlsafe_decode64(value.ljust((value.length + 3) / 4 * 4, "="))
+      raise InvalidEncodingError, "non-canonical Base64url" unless encode(bytes) == value
+      raise InvalidEncodingError, "expected #{length} bytes" if length && bytes.bytesize != length
+
+      bytes
+    rescue ArgumentError => error
+      raise InvalidEncodingError, error.message
+    end
+  end
+end

data/lib/opp/canonicalization.rb

@@ -0,0 +1,69 @@
+require "json/canonicalization"
+
+module OPP
+  module Canonicalization
+    class NumberAdapter
+      def initialize(value)
+        @value = value.to_f
+      end
+
+      def to_json_c14n
+        Canonicalization.send(:serialize_float, @value)
+      end
+    end
+    private_constant :NumberAdapter
+
+    module_function
+
+    def canonicalize(value)
+      adapt(value).to_json_c14n.encode(Encoding::UTF_8)
+    rescue StandardError => error
+      raise if error.is_a?(OPP::Error)
+
+      raise CanonicalizationError, error.message
+    end
+
+    def adapt(value)
+      case value
+      when Integer, Float
+        NumberAdapter.new(value)
+      when Hash
+        value.to_h { |key, member| [key, adapt(member)] }
+      when Array
+        value.map { |member| adapt(member) }
+      else
+        value
+      end
+    end
+    private_class_method :adapt
+
+    def serialize_float(value)
+      raise RangeError, "non-finite number" unless value.finite?
+      return "0" if value.zero?
+
+      representation = value.to_s
+      sign = representation.delete_prefix!("-") ? "-" : ""
+      return sign + representation.delete_suffix(".0") unless representation.include?("e")
+
+      mantissa, exponent_text = representation.split("e")
+      exponent = exponent_text.to_i
+      digits = mantissa.end_with?(".0") ? mantissa.delete_suffix(".0") : mantissa.delete(".")
+
+      if exponent.between?(-6, 20)
+        decimal_position = exponent + 1
+        decimal = if decimal_position <= 0
+                    "0." + ("0" * -decimal_position) + digits
+                  elsif decimal_position >= digits.length
+                    digits + ("0" * (decimal_position - digits.length))
+                  else
+                    digits.dup.insert(decimal_position, ".")
+                  end
+        sign + decimal
+      else
+        coefficient = digits.length == 1 ? digits : digits.dup.insert(1, ".")
+        sign + coefficient + "e" + (exponent.positive? ? "+" : "") + exponent.to_s
+      end
+    end
+    private_class_method :serialize_float
+  end
+end

data/lib/opp/errors.rb

@@ -0,0 +1,23 @@
+module OPP
+  class Error < StandardError
+    attr_reader :code, :path
+
+    def initialize(message = nil, code: nil, path: nil)
+      super(message)
+      @code = code || self.class.name.split("::").last
+        .gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase.delete_suffix("_error")
+      @path = path
+    end
+  end
+
+  ParseError = Class.new(Error)
+  DuplicateMemberError = Class.new(Error)
+  ValidationError = Class.new(Error)
+  CanonicalizationError = Class.new(Error)
+  InvalidEncodingError = Class.new(Error)
+  InvalidPublicKeyError = Class.new(Error)
+  SubjectMismatchError = Class.new(Error)
+  InvalidSignatureError = Class.new(Error)
+  ExpiredDocumentError = Class.new(Error)
+  UnsupportedVersionError = Class.new(Error)
+end

data/lib/opp/json.rb

@@ -0,0 +1,43 @@
+require "json"
+
+module OPP
+  module JSON
+    class DuplicateCheckingHash < Hash
+      def []=(key, value)
+        raise DuplicateMemberError, "duplicate JSON member: #{key}" if key?(key)
+
+        super
+      end
+    end
+    private_constant :DuplicateCheckingHash
+
+    module_function
+
+    def parse(input)
+      plain_value(::JSON.parse(input, object_class: DuplicateCheckingHash))
+    rescue ::JSON::ParserError, EncodingError => error
+      raise ParseError, error.message
+    end
+
+    def plain_value(value)
+      case value
+      when DuplicateCheckingHash
+        value.to_h { |key, member| [valid_string(key), plain_value(member)] }
+      when Array
+        value.map { |member| plain_value(member) }
+      when String
+        valid_string(value)
+      else
+        value
+      end
+    end
+    private_class_method :plain_value
+
+    def valid_string(value)
+      raise EncodingError, "invalid Unicode in JSON string" unless value.valid_encoding?
+
+      value
+    end
+    private_class_method :valid_string
+  end
+end

data/lib/opp/key_pair.rb

@@ -0,0 +1,27 @@
+require "ed25519"
+
+module OPP
+  class KeyPair
+    attr_reader :private_key, :public_key
+
+    def self.generate
+      new(Ed25519::SigningKey.generate)
+    end
+
+    def self.from_private_key(value)
+      new(Ed25519::SigningKey.new(Base64URL.decode(value, length: 32)))
+    end
+
+    def initialize(signing_key)
+      @signing_key = signing_key
+      @private_key = Base64URL.encode(signing_key.to_bytes)
+      @public_key = Base64URL.encode(signing_key.verify_key.to_bytes)
+    end
+
+    def sign(bytes)
+      @signing_key.sign(bytes)
+    end
+
+    private_class_method :new
+  end
+end

data/lib/opp/presence.rb

@@ -0,0 +1,197 @@
+require "date"
+require "time"
+require "uri"
+
+module OPP
+  module Presence
+    REQUIRED = %w[type version subject public_key issued_at services signature].freeze
+    TYPES = {
+      "type" => String,
+      "version" => String,
+      "subject" => String,
+      "public_key" => String,
+      "issued_at" => String,
+      "services" => Array,
+      "signature" => Hash,
+      "expires_at" => String
+    }.freeze
+    TIMESTAMP_PATTERN = /\A(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.(?<fraction>\d+))?Z\z/
+
+    module_function
+
+    def sign(document, private_key:)
+      raise ValidationError, "document must be an object" unless document.is_a?(Hash)
+
+      pair = KeyPair.from_private_key(private_key)
+      unsigned = copy(document).tap { |value| value.delete("signature") }.merge(
+        "public_key" => pair.public_key,
+        "subject" => Subject.derive(pair.public_key)
+      )
+      errors = validate(unsigned, at: nil, signature_required: false)
+      raise errors.first unless errors.empty?
+
+      Signature.sign(unsigned, private_key:)
+    end
+
+    def verify(input, at: Time.now.utc)
+      document = input.is_a?(String) ? OPP::JSON.parse(input) : copy(input)
+      VerificationResult.new(validate(document, at:, signature_required: true))
+    rescue OPP::Error => error
+      VerificationResult.new([error])
+    end
+
+    def verify!(input, at: Time.now.utc)
+      result = verify(input, at:)
+      raise result.errors.first unless result.valid?
+
+      true
+    end
+
+    def validate(document, at:, signature_required:)
+      return [ValidationError.new("document must be an object")] unless document.is_a?(Hash)
+
+      errors = required_errors(document, signature_required:)
+      errors.concat(type_errors(document))
+      errors << ValidationError.new("type must be open-presence", path: "type") if
+        document["type"].is_a?(String) && document["type"] != "open-presence"
+      errors << UnsupportedVersionError.new("unsupported version: #{document["version"]}", path: "version") if
+        document["version"].is_a?(String) && document["version"] != "0.1"
+
+      public_key_usable = validate_credentials(document, errors)
+      validate_timestamps(document, at:, errors:)
+      validate_services(document, errors)
+      if signature_required && public_key_usable && document["signature"].is_a?(Hash)
+        begin
+          Signature.verify!(document, public_key: document["public_key"])
+        rescue OPP::Error => error
+          errors << error
+        end
+      end
+      errors
+    end
+    private_class_method :validate
+
+    def required_errors(document, signature_required:)
+      required = signature_required ? REQUIRED : REQUIRED - ["signature"]
+      required.filter_map do |field|
+        ValidationError.new("missing required field: #{field}", path: field) unless document.key?(field)
+      end
+    end
+    private_class_method :required_errors
+
+    def type_errors(document)
+      TYPES.filter_map do |field, type|
+        next unless document.key?(field) && !document[field].is_a?(type)
+
+        ValidationError.new("#{field} must be #{type.name.downcase}", path: field)
+      end
+    end
+    private_class_method :type_errors
+
+    def validate_credentials(document, errors)
+      return false unless document["public_key"].is_a?(String)
+
+      begin
+        PublicKey.decode(document["public_key"])
+      rescue InvalidPublicKeyError => error
+        errors << InvalidPublicKeyError.new(error.message, path: "public_key")
+        return false
+      end
+
+      if document["subject"].is_a?(String)
+        begin
+          Subject.verify!(document["subject"], public_key: document["public_key"])
+        rescue SubjectMismatchError => error
+          errors << SubjectMismatchError.new(error.message, path: "subject")
+        end
+      end
+      true
+    end
+    private_class_method :validate_credentials
+
+    def validate_timestamps(document, at:, errors:)
+      issued_at = parse_timestamp(document, "issued_at", errors)
+      expires_at = parse_timestamp(document, "expires_at", errors) if document.key?("expires_at")
+      return unless expires_at
+
+      if issued_at && expires_at <= issued_at
+        errors << ValidationError.new("expires_at must be later than issued_at", path: "expires_at")
+      end
+      if at && at >= expires_at
+        errors << ExpiredDocumentError.new("document has expired", path: "expires_at")
+      end
+    end
+    private_class_method :validate_timestamps
+
+    def parse_timestamp(document, field, errors)
+      value = document[field]
+      return unless value.is_a?(String)
+
+      match = TIMESTAMP_PATTERN.match(value)
+      unless match
+        errors << ValidationError.new("#{field} must be an RFC 3339 UTC timestamp", path: field)
+        return
+      end
+
+      year, month, day, hour, minute, second =
+        %i[year month day hour minute second].map { |component| match[component].to_i }
+      date = Date.new(year, month, day)
+      raise ArgumentError unless hour.between?(0, 23) && minute.between?(0, 59) && second.between?(0, 60)
+      raise ArgumentError if second == 60 && (hour != 23 || minute != 59 || date.next_day.day != 1)
+
+      fraction = match[:fraction] ? Rational(match[:fraction].to_i, 10**match[:fraction].length) : 0
+      Time.utc(year, month, day, hour, minute, [second, 59].min) + fraction + (second == 60 ? 1 : 0)
+    rescue ArgumentError
+      errors << ValidationError.new("#{field} must be a valid timestamp", path: field)
+      nil
+    end
+    private_class_method :parse_timestamp
+
+    def validate_services(document, errors)
+      return unless document["services"].is_a?(Array)
+
+      document["services"].each_with_index do |service, index|
+        base = "services[#{index}]"
+        unless service.is_a?(Hash)
+          errors << ValidationError.new("#{base} must be an object", path: base)
+          next
+        end
+
+        %w[type url].each do |field|
+          errors << ValidationError.new("missing required field: #{base}.#{field}", path: "#{base}.#{field}") unless
+            service.key?(field)
+        end
+        %w[type url].each do |field|
+          errors << ValidationError.new("#{base}.#{field} must be a string", path: "#{base}.#{field}") if
+            service.key?(field) && !service[field].is_a?(String)
+        end
+        validate_service_url(service["url"], "#{base}.url", errors) if service["url"].is_a?(String)
+      end
+    end
+    private_class_method :validate_services
+
+    def validate_service_url(value, path, errors)
+      uri = ::URI.parse(value)
+      return if uri.is_a?(::URI::HTTPS) && !uri.host.to_s.empty? && uri.user.nil? && uri.password.nil?
+
+      errors << ValidationError.new("#{path} must be an absolute credential-free HTTPS URL", path: path)
+    rescue ::URI::InvalidURIError
+      errors << ValidationError.new("#{path} must be a valid URL", path: path)
+    end
+    private_class_method :validate_service_url
+
+    def copy(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key, copy(item)] }
+      when Array
+        value.map { |item| copy(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+    private_class_method :copy
+  end
+end

data/lib/opp/public_key.rb

@@ -0,0 +1,15 @@
+require "ed25519"
+
+module OPP
+  module PublicKey
+    module_function
+
+    def decode(value)
+      bytes = Base64URL.decode(value, length: 32)
+      Ed25519::VerifyKey.new(bytes)
+      bytes
+    rescue InvalidEncodingError => error
+      raise InvalidPublicKeyError, error.message
+    end
+  end
+end

data/lib/opp/signature.rb

@@ -0,0 +1,76 @@
+require "ed25519"
+
+module OPP
+  module Signature
+    module_function
+
+    def sign(document, private_key:)
+      unsigned = unsigned_document(document)
+      bytes = KeyPair.from_private_key(private_key)
+        .sign(Canonicalization.canonicalize(unsigned))
+
+      unsigned.merge(
+        "signature" => {
+          "algorithm" => "ed25519",
+          "value" => Base64URL.encode(bytes)
+        }
+      )
+    rescue InvalidEncodingError => error
+      raise InvalidSignatureError, error.message
+    end
+
+    def verify(document, public_key:)
+      verify!(document, public_key:)
+    rescue InvalidSignatureError
+      false
+    end
+
+    def verify!(document, public_key:)
+      unsigned, signature = split(document)
+      unless signature["algorithm"] == "ed25519"
+        raise InvalidSignatureError, "unsupported signature algorithm"
+      end
+
+      bytes = Base64URL.decode(signature["value"], length: 64)
+      verify_key = Ed25519::VerifyKey.new(PublicKey.decode(public_key))
+      verify_key.verify(bytes, Canonicalization.canonicalize(unsigned))
+      true
+    rescue Ed25519::VerifyError, InvalidEncodingError, InvalidPublicKeyError => error
+      raise InvalidSignatureError, error.message
+    end
+
+    def split(document)
+      unsigned = unsigned_document(document)
+      signature = document["signature"]
+      unless signature.is_a?(Hash) &&
+          signature["algorithm"].is_a?(String) &&
+          signature["value"].is_a?(String)
+        raise InvalidSignatureError, "invalid signature object"
+      end
+
+      [unsigned, copy(signature)]
+    end
+    private_class_method :split
+
+    def unsigned_document(document)
+      raise ValidationError, "document must be an object" unless document.is_a?(Hash)
+
+      copy(document).tap { |value| value.delete("signature") }
+    end
+    private_class_method :unsigned_document
+
+    def copy(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key, copy(item)] }
+      when Array
+        value.map { |item| copy(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+    private_class_method :copy
+  end
+end

data/lib/opp/subject.rb

@@ -0,0 +1,26 @@
+require "digest"
+
+module OPP
+  module Subject
+    PREFIX = "key:sha256:"
+
+    module_function
+
+    def derive(public_key)
+      PREFIX + Base64URL.encode(Digest::SHA256.digest(PublicKey.decode(public_key)))
+    end
+
+    def verify!(subject, public_key:)
+      return true if subject.is_a?(String) && secure_equal(subject, derive(public_key))
+
+      raise SubjectMismatchError, "subject does not match public key"
+    end
+
+    def secure_equal(left, right)
+      left.bytesize == right.bytesize && left.bytes.zip(right.bytes).reduce(0) do |difference, (a, b)|
+        difference | (a ^ b)
+      end.zero?
+    end
+    private_class_method :secure_equal
+  end
+end

data/lib/opp/verification_result.rb

@@ -0,0 +1,13 @@
+module OPP
+  class VerificationResult
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors.freeze
+    end
+
+    def valid?
+      errors.empty?
+    end
+  end
+end

data/lib/opp/version.rb

@@ -0,0 +1,3 @@
+module OPP
+  VERSION = "0.1.0"
+end

data/lib/opp.rb

@@ -0,0 +1,11 @@
+require_relative "opp/version"
+require_relative "opp/errors"
+require_relative "opp/base64_url"
+require_relative "opp/public_key"
+require_relative "opp/key_pair"
+require_relative "opp/subject"
+require_relative "opp/json"
+require_relative "opp/canonicalization"
+require_relative "opp/signature"
+require_relative "opp/verification_result"
+require_relative "opp/presence"

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: open-presence
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jody Dawkins
+bindir: bin
+cert_chain: []
+date: 2026-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: json-canonicalization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/opp.rb
+- lib/opp/base64_url.rb
+- lib/opp/canonicalization.rb
+- lib/opp/errors.rb
+- lib/opp/json.rb
+- lib/opp/key_pair.rb
+- lib/opp/presence.rb
+- lib/opp/public_key.rb
+- lib/opp/signature.rb
+- lib/opp/subject.rb
+- lib/opp/verification_result.rb
+- lib/opp/version.rb
+homepage: https://github.com/jodydawkins/opp-ruby
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Open Presence Protocol for Ruby
+test_files: []