oydid 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3e561caa744ec1b341317d142b27f5b9d7d9dddf92b2d18aaf2117fff05cb9a
-  data.tar.gz: 6aa242687b1765148f79e9b6911d22e81339159f2f0c45445c0be1ce804fe0ad
+  metadata.gz: 9c74b5cd9e592efe1514c9110cff25a131ddc0a45727e035d48656bc0c20d2f8
+  data.tar.gz: bd936eb03e018e15ae334907c7087629f48f17c2cc54bdeebb8a81542e2f2af9
 SHA512:
-  metadata.gz: 35d735d7f16edf812645b91034b5c8824437144fb86b2dba19e2b165a1912279fc3e6b09916cde37004402bb309f5faad7248105b41de07f293892f7e6963d09
-  data.tar.gz: 0e333ede2a2b46e9c6264264f638cf3b54823cab9663a11af3bf776f796965210abb39b3c37555d0824f67d9b55506d3065803b1a94182097acdf0b11b9c670e
+  metadata.gz: 8fddcdf2ce2328ba9329263b1de2826cec3c3d4947c7cd5e599972798cffb10887e8bf2205d208961494a7296a818c90a4fea679f2b9b1c01109645c8fde59bf
+  data.tar.gz: fdaab3ac52a14b4313db2d7d52058a41bdd6b72b2ca580441f5620a246d73d2fdf753a0530aef76d44520d8347573852aa6e3ae27d173371d54b09eeb86c874c

data/VERSION

@@ -1 +1 @@
-0.9.0
+0.9.1

data/lib/oydid/basic.rb

@@ -1216,6 +1216,24 @@ class Oydid
         end
     end
 
+    # The identifier without its location suffix.
+    #
+    # A did:oyd can carry "@<location>" (raw or percent-encoded) to say where the
+    # document is hosted. That is a resolution hint, not part of the identity:
+    # the same document can be mirrored at any number of locations, so the set of
+    # location-bound variants is open and cannot be enumerated. Everything that
+    # states identity - canonicalId and equivalentId in the didDocumentMetadata -
+    # therefore uses this location-free form. The location-bound variant stays in
+    # alsoKnownAs.
+    #
+    # Note this must NOT be applied to the id of the DID document itself: DID Core
+    # requires that "the value of the id property in the retrieved DID document
+    # must always match the DID being resolved", so a location-bound DID that was
+    # requested is echoed as requested (see Oydid.document_id).
+    def self.strip_location(id)
+        id.to_s.split(LOCATION_PREFIX).first.split(CGI.escape LOCATION_PREFIX).first rescue id.to_s
+    end
+
     def self.get_location(id)
         if id.include?(LOCATION_PREFIX)
             id_split = id.split(LOCATION_PREFIX)

data/lib/oydid.rb

@@ -1446,19 +1446,42 @@ class Oydid
     # uniresolver plugin) and they had drifted into computing this list with
     # different rules.
     #
+    # Both values are location-free: the "@<location>" suffix says where a
+    # document is hosted, not who it is, and the same document can be mirrored at
+    # any number of locations - so the set of location-bound variants is open and
+    # equivalentId could not state it correctly anyway. The raw values these are
+    # built from do carry a location (dag_update sets did_info["did"] from the log
+    # entry, and log[]["doc"] is written with one), which is why strip_location is
+    # applied here rather than assumed. The location-bound variant stays in
+    # alsoKnownAs; document_id is deliberately left alone (see strip_location).
+    #
     # Returns [canonicalId, equivalentIds]; equivalentIds never contains the
-    # identifier the DID document itself carries as `id` (see document_id).
-    def self.version_ids(did_info)
-        canonical = percent_encode(did_info["did"].to_s)
-        if !canonical.start_with?("did:oyd:")
-            canonical = "did:oyd:" + canonical
-        end
+    # identifier the DID document itself carries as `id` (see document_id) and is
+    # empty - not a set with the DID itself in it - while there is only one
+    # version.
+    # keep_location = true reproduces the pre-0.9.1 values, location suffix and
+    # all. Only w3c uses it, to keep alsoKnownAs listing the location-bound
+    # variant of a DID - dropping that would take the location out of the
+    # document altogether, and alsoKnownAs is where it belongs.
+    #
+    # Deliberately a positional argument: callers pass did_info as a braceless
+    # hash literal (version_ids("did" => ..., "log" => ...)), and a method with
+    # a keyword parameter swallows that hash as keywords instead - every such
+    # call site would raise ArgumentError.
+    def self.version_ids(did_info, keep_location = false)
+        normalize = lambda do |id|
+            id = keep_location ? id.to_s : strip_location(id.to_s)
+            id = percent_encode(id)
+            id = "did:oyd:" + id if !id.start_with?("did:oyd:")
+            id
+        end
+        canonical = normalize.call(did_info["did"])
         own = document_id(did_info)
         equivalentIds = []
         did_info["log"].each do |log|
             if log["op"] == 2 || log["op"] == 3
-                eid = percent_encode("did:oyd:" + log["doc"].to_s)
-                if eid != own
+                eid = normalize.call(log["doc"])
+                if eid != own && !equivalentIds.include?(eid)
                     equivalentIds << eid
                 end
             end
@@ -1466,6 +1489,52 @@ class Oydid
         [canonical, equivalentIds]
     end
 
+    # created / updated / versionId of the resolved document version, as DID Core
+    # 7.1.3 defines them. Returned as a hash with string keys, ready to be merged
+    # into didDocumentMetadata; a property the log cannot answer is absent rather
+    # than null - in particular `updated`, which the spec requires to be "omitted
+    # if an Update operation has never been performed on the DID document".
+    #
+    # The resolved version is did_info["did"] - dag_update walks the log to the
+    # newest document and leaves its identifier there. Deriving both versionId and
+    # the `updated` entry from it avoids guessing which log entry is the newest,
+    # which timestamps alone cannot decide (they are client-supplied and two
+    # entries can share a second).
+    #
+    # versionId is the bare document hash, without the "did:oyd:" prefix and
+    # without a location: it is the method-specific identifier of that version, so
+    # "did:oyd:" + versionId is the versioned DID.
+    def self.version_metadata(did_info)
+        as_datetime = lambda do |ts|
+            # XML Datetime normalised to UTC, no sub-second precision (7.1.3)
+            Time.at(ts.to_i).utc.strftime("%Y-%m-%dT%H:%M:%SZ") rescue nil
+        end
+        version_of = lambda do |id|
+            strip_location(id.to_s).delete_prefix("did:oyd:")
+        end
+
+        meta = {}
+        resolved = version_of.call(did_info["did"])
+        meta["versionId"] = resolved if resolved != ""
+        return meta if did_info["log"].nil?
+
+        created_entry = did_info["log"].find { |el| el["op"].to_i == 2 }
+        if !created_entry.nil? && !created_entry["ts"].nil?
+            created = as_datetime.call(created_entry["ts"])
+            meta["created"] = created if !created.nil?
+        end
+
+        updated_entry = did_info["log"].find do |el|
+            el["op"].to_i == 3 && version_of.call(el["doc"]) == resolved
+        end
+        if !updated_entry.nil? && !updated_entry["ts"].nil?
+            updated = as_datetime.call(updated_entry["ts"])
+            meta["updated"] = updated if !updated.nil?
+        end
+
+        meta
+    end
+
     # The identifier a resolved DID document carries as `id`.
     #
     # A did:oyd is the hash over its own document, so an update mints a new one
@@ -1632,8 +1701,12 @@ class Oydid
         # is reciprocated - which it cannot be here, because all versions resolve
         # to the same document. It stays for backwards compatibility; the
         # authoritative statement is didDocumentMetadata canonicalId/equivalentId,
-        # built from the same list.
-        equivalentIds = version_ids(did_info).last
+        # built from the same list - except that this one keeps the location
+        # suffix. alsoKnownAs therefore carries two kinds of statement: other
+        # versions of the DID, and the location-bound variant of one. It must not
+        # be read as a list of locations; the method specification says so
+        # explicitly.
+        equivalentIds = version_ids(did_info, true).last
         if equivalentIds.length > 0
             wd["alsoKnownAs"] = equivalentIds
         end

data/spec/oydid_spec.rb

@@ -626,12 +626,80 @@ describe "OYDID handling" do
       expect(canonical).to eq "did:oyd:" + second_did
     end
 
-    it "percent-encodes a location suffix" do
+    # The identifier a relying party was handed is the one it asked for, which
+    # after an update is an earlier version than the document being served. Every
+    # other version is then equivalent to it - not just the current one. This is
+    # the case the HTTP request specs could not reach before update_did existed.
+    it "lists every other version when an earlier one was requested" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:zC",
+        "did_requested" => "did:oyd:zA",
+        "log" => [{ "op" => 2, "doc" => "zA" },
+                  { "op" => 3, "doc" => "zB" },
+                  { "op" => 3, "doc" => "zC" }])
+      expect(canonical).to eq "did:oyd:zC"
+      expect(equivalent).to eq ["did:oyd:zB", "did:oyd:zC"]
+    end
+
+    it "lists the versions on both sides when a middle one was requested" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:zC",
+        "did_requested" => "did:oyd:zB",
+        "log" => [{ "op" => 2, "doc" => "zA" },
+                  { "op" => 3, "doc" => "zB" },
+                  { "op" => 3, "doc" => "zC" }])
+      expect(canonical).to eq "did:oyd:zC"
+      expect(equivalent).to eq ["did:oyd:zA", "did:oyd:zC"]
+    end
+
+    # canonicalId and equivalentId state identity, and "@<location>" states where
+    # a document is hosted. The same document can be mirrored at any number of
+    # locations, so the set of location-bound variants is open and equivalentId
+    # could not state it correctly - both are therefore location-free.
+    it "strips the location suffix from canonicalId and equivalentId" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:" + second_did + "@https://example.org",
+        "did_requested" => "did:oyd:" + second_did,
+        "log" => [{ "op" => 2, "doc" => first_did + "@https://example.org" },
+                  { "op" => 3, "doc" => second_did + "@https://example.org" }])
+      expect(canonical).to eq "did:oyd:" + second_did
+      expect(equivalent).to eq ["did:oyd:" + first_did]
+    end
+
+    # A location-bound DID that was asked for stays the id of the document - DID
+    # Core: "the value of the id property in the retrieved DID document must
+    # always match the DID being resolved". Its location-free form is then a
+    # genuinely different string for the same subject, so it belongs in
+    # equivalentId alongside the earlier version.
+    it "lists the location-free form of the current version when a location-bound DID was requested" do
       canonical, equivalent = Oydid.version_ids(
         "did" => "did:oyd:" + second_did + "@https://example.org",
+        "did_requested" => "did:oyd:" + second_did + "@https://example.org",
         "log" => [{ "op" => 2, "doc" => first_did + "@https://example.org" },
                   { "op" => 3, "doc" => second_did + "@https://example.org" }])
-      expect(canonical).to eq "did:oyd:" + second_did + "%40example.org"
+      expect(canonical).to eq "did:oyd:" + second_did
+      expect(equivalent).to eq ["did:oyd:" + first_did, "did:oyd:" + second_did]
+    end
+
+    # this used to list the DID as its own equivalent, in location-bound form,
+    # and hand out that same string as canonicalId
+    it "reports no equivalents for a never updated DID served from a location" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:" + first_did + "@https://example.org",
+        "did_requested" => "did:oyd:" + first_did,
+        "log" => [{ "op" => 2, "doc" => first_did + "@https://example.org" },
+                  { "op" => 0, "doc" => "terminate" }])
+      expect(canonical).to eq "did:oyd:" + first_did
+      expect(equivalent).to eq []
+    end
+
+    it "keeps the location suffix for the alsoKnownAs list" do
+      canonical, equivalent = Oydid.version_ids(
+        { "did" => "did:oyd:" + first_did + "@https://example.org",
+          "did_requested" => "did:oyd:" + first_did,
+          "log" => [{ "op" => 2, "doc" => first_did + "@https://example.org" }] },
+        true)
+      expect(canonical).to eq "did:oyd:" + first_did + "%40example.org"
       expect(equivalent).to eq ["did:oyd:" + first_did + "%40example.org"]
     end
 
@@ -661,7 +729,78 @@ describe "OYDID handling" do
       }
       wd = Oydid.w3c(Marshal.load(Marshal.dump(did_info)), {})
       expect(wd["alsoKnownAs"]).to eq ["did:oyd:" + first_did]
-      expect(wd["alsoKnownAs"]).to eq Oydid.version_ids(did_info).last
+      expect(wd["alsoKnownAs"]).to eq Oydid.version_ids(did_info, true).last
+    end
+
+    # The two lists deliberately part ways on the location: identity statements
+    # drop it, alsoKnownAs keeps it - otherwise the location would disappear from
+    # the DID document altogether. Guards the live output for a never updated DID.
+    it "keeps the location-bound variant in alsoKnownAs while canonicalId drops it" do
+      stubbed_did = "zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh"
+      did_info = {
+        "did" => "did:oyd:" + stubbed_did + "@https://example.org",
+        "did_requested" => "did:oyd:" + stubbed_did,
+        "doc" => { "doc" => { "hello" => "world" },
+                   "key" => "z6MktULudTtAsAhRegYPiZ6631RV3viv12qd4GQF8z1xB22S:" \
+                            "z6MkqGC3nWZhYieEVTVDKW5v588CiGfsDSmRVG9ZwwWTvLSK" },
+        "log" => [{ "op" => 2, "doc" => stubbed_did + "@https://example.org" }]
+      }
+      wd = Oydid.w3c(Marshal.load(Marshal.dump(did_info)), {})
+      expect(wd["id"]).to eq "did:oyd:" + stubbed_did
+      expect(wd["alsoKnownAs"]).to eq ["did:oyd:" + stubbed_did + "%40example.org"]
+      canonical, equivalent = Oydid.version_ids(did_info)
+      expect(canonical).to eq "did:oyd:" + stubbed_did
+      expect(equivalent).to eq []
+    end
+  end
+
+  # created / updated / versionId of the resolved version (DID Core 7.1.3).
+  # Without `updated` a consumer cannot tell how old the document in its hands is.
+  describe "version_metadata" do
+    let(:first_did)  { "zQmSE1hzumtZ7AoK1qhHf4t5kiKsujMsJSHqoXtWrdd7K7W" }
+    let(:second_did) { "zQmfEb3KgYZjZUPLTHPmFPdcV6peF5itB5NmJ9N6gaxxE8K" }
+
+    # "The updated property is omitted if an Update operation has never been
+    # performed on the DID document." - 7.1.3
+    it "reports created and versionId, and omits updated, for a new DID" do
+      meta = Oydid.version_metadata(
+        "did" => "did:oyd:" + first_did + "@https://example.org",
+        "log" => [{ "op" => 2, "ts" => 1641224940, "doc" => first_did + "@https://example.org" },
+                  { "op" => 0, "ts" => 1641224940, "doc" => "terminate" }])
+      expect(meta["created"]).to eq "2022-01-03T15:49:00Z"
+      expect(meta["versionId"]).to eq first_did
+      expect(meta).not_to have_key("updated")
+    end
+
+    it "reports the timestamp of the update that produced the resolved version" do
+      meta = Oydid.version_metadata(
+        "did" => "did:oyd:" + second_did,
+        "log" => [{ "op" => 2, "ts" => 1641224940, "doc" => first_did },
+                  { "op" => 3, "ts" => 1641225032, "doc" => second_did },
+                  { "op" => 0, "ts" => 1641225032, "doc" => "terminate" }])
+      expect(meta["created"]).to eq "2022-01-03T15:49:00Z"
+      expect(meta["updated"]).to eq "2022-01-03T15:50:32Z"
+      expect(meta["versionId"]).to eq second_did
+    end
+
+    # the entry is picked by the version it produced, not by its timestamp:
+    # timestamps come from the client and two entries can share a second
+    it "ignores updates that did not produce the resolved version" do
+      meta = Oydid.version_metadata(
+        "did" => "did:oyd:zB",
+        "log" => [{ "op" => 2, "ts" => 1, "doc" => "zA" },
+                  { "op" => 3, "ts" => 2, "doc" => "zB" },
+                  { "op" => 3, "ts" => 3, "doc" => "zC" }])
+      expect(meta["versionId"]).to eq "zB"
+      expect(meta["updated"]).to eq "1970-01-01T00:00:02Z"
+    end
+
+    it "leaves out what the log cannot answer" do
+      expect(Oydid.version_metadata("did" => "did:oyd:" + first_did))
+        .to eq({ "versionId" => first_did })
+      expect(Oydid.version_metadata("did" => "did:oyd:" + first_did,
+                                    "log" => [{ "op" => 2, "doc" => first_did }]))
+        .to eq({ "versionId" => first_did })
     end
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: oydid
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Christoph Fabianek
 bindir: bin
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simple_dag