oydid 0.8.2 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66decf23cb4e474d0703a8948e20474be619c05083bd8abd5ab8d45857ac4ac0
-  data.tar.gz: db83f3c7ba0a20c5e4f8fd8ba8b9977b42b9b78fc56ad11df8a8bf12e9657704
+  metadata.gz: 9c74b5cd9e592efe1514c9110cff25a131ddc0a45727e035d48656bc0c20d2f8
+  data.tar.gz: bd936eb03e018e15ae334907c7087629f48f17c2cc54bdeebb8a81542e2f2af9
 SHA512:
-  metadata.gz: 8856635688f0dd47b246443d7fcc7a994ceef87e7d2594530da0f3489445a544f3c7cc9d20327fec7da3988e83872d1ddf3c854bd4db25b367b72fa917ba09c3
-  data.tar.gz: '08956cf2da8ed63a35261a7ffa01cb58b11a177c77fe8b5f873f8ed4d59592695c0e80bd72d118c28f4266728b10e420b4eaab7189c406dd6c7731e52f40e38d'
+  metadata.gz: 8fddcdf2ce2328ba9329263b1de2826cec3c3d4947c7cd5e599972798cffb10887e8bf2205d208961494a7296a818c90a4fea679f2b9b1c01109645c8fde59bf
+  data.tar.gz: fdaab3ac52a14b4313db2d7d52058a41bdd6b72b2ca580441f5620a246d73d2fdf753a0530aef76d44520d8347573852aa6e3ae27d173371d54b09eeb86c874c

data/VERSION

@@ -1 +1 @@
-0.8.2
+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

@@ -68,8 +68,15 @@ class Oydid
         end
 
         # setup
+        #
+        # did_requested is the identifier the caller asked for. dag_update
+        # overwrites "did" with every version it walks through, so by the time a
+        # DID document is rendered the requested identifier would be lost - and
+        # after an update that is exactly the one a relying party holds, e.g.
+        # printed on a product's data carrier.
         currentDID = {
             "did": did,
+            "did_requested": did,
             "doc": "",
             "log": [],
             "doc_log_id": nil,
@@ -1426,6 +1433,130 @@ class Oydid
         wd
     end
 
+    # Identifiers of every published version of a DID, oldest first.
+    #
+    # A did:oyd is the hash over its own DID document, so every update mints a
+    # new identifier while the earlier ones stay resolvable through the log.
+    # The version reached by traversing the log is the canonical identifier,
+    # every other version identifier is logically equivalent to it - which is
+    # what DID Core expresses as didDocumentMetadata canonicalId/equivalentId.
+    #
+    # This lives in the gem rather than in the resolving controllers because
+    # there are three of them (repository resolve and resolve_full, plus the
+    # 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) 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 = normalize.call(log["doc"])
+                if eid != own && !equivalentIds.include?(eid)
+                    equivalentIds << eid
+                end
+            end
+        end unless did_info["log"].nil?
+        [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
+    # and the resolution walks the log to the newest version. Answering with that
+    # newest identifier means a relying party never sees the DID it asked for -
+    # the one on the data carrier, in the credential, in the database. So the
+    # requested identifier is what goes into the document; which version it is
+    # remains readable from didDocumentMetadata canonicalId.
+    #
+    # Callers that build a did_info by hand - the registrar endpoints do, for a
+    # DID that was just created or updated - carry no did_requested and keep
+    # getting the identifier they passed in.
+    def self.document_id(did_info)
+        did = did_info["did_requested"].to_s
+        did = did_info["did"].to_s if did == ""
+        did = percent_encode(did)
+        if !did.start_with?("did:oyd:")
+            did = "did:oyd:" + did
+        end
+        did
+    end
+
     def self.w3c(did_info, options)
         # check if doc is already W3C DID
         is_already_w3c_did = (did_info.transform_keys(&:to_s)["doc"]["doc"].has_key?("@context") &&
@@ -1434,10 +1565,7 @@ class Oydid
         if is_already_w3c_did
             return did_info.transform_keys(&:to_s)["doc"]["doc"]
         end
-        did = percent_encode(did_info["did"])
-        if !did.start_with?("did:oyd:")
-            did = "did:oyd:" + did
-        end
+        did = document_id(did_info)
 
         didDoc = did_info.dup.transform_keys(&:to_s)["doc"]
         pubDocKey = didDoc["key"].split(":")[0] rescue ""
@@ -1568,15 +1696,17 @@ class Oydid
             end
         end
 
-        equivalentIds = []
-        did_info["log"].each do |log|
-            if log["op"] == 2 || log["op"] == 3
-                eid = percent_encode("did:oyd:" + log["doc"])
-                if eid != did
-                    equivalentIds << eid
-                end
-            end
-        end unless did_info["log"].nil?
+        # alsoKnownAs is a statement about the DID *subject*, and DID Core calls
+        # it best practice not to read it as equivalence unless the relationship
+        # 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 - 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/output/main/sample0_read.doc

@@ -1 +1 @@
-[{"did":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","doc":{"doc":{"simple":"example"},"key":"z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ:z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB","log":"zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe"},"log":[{"ts":1641224736,"op":2,"doc":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","sig":"z3Kb5qeReCqr3ftxpf2i5UypUwrzrVkyspMtaDcb6e9YdHVSptcAFgvwbgk3qWqspTcGiKDYKXZZh8g6XyM2WPmNp","previous":[]},{"ts":1641224736,"op":0,"doc":"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS","sig":"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU","previous":[]}],"doc_log_id":0,"termination_log_id":1,"error":0,"message":"","verification":"identifier: zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh\n✅ is hash of DID Document:\n{\n  \"doc\": {\n    \"simple\": \"example\"\n  },\n  \"key\": \"z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ:z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB\",\n  \"log\": \"zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe\"\n}\n(Details: https://ownyourdata.github.io/oydid/#calculate_hash)\n\n'log' reference in DID Document: zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe\n✅ is hash of TERMINATE log record:\n{\n  \"ts\": 1641224736,\n  \"op\": 0,\n  \"doc\": \"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS\",\n  \"sig\": \"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU\",\n  \"previous\": []\n}\n(Details: https://ownyourdata.github.io/oydid/#calculate_hash)\n\nRevocation reference in log record: zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS\n✅ cannot find revocation record searching at\n- https://oydid.ownyourdata.eu\n(Details: https://ownyourdata.github.io/oydid/#retrieve_log)\n\n","full_log":[{"ts":1641224736,"op":2,"doc":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","sig":"z3Kb5qeReCqr3ftxpf2i5UypUwrzrVkyspMtaDcb6e9YdHVSptcAFgvwbgk3qWqspTcGiKDYKXZZh8g6XyM2WPmNp","previous":[]},{"ts":1641224736,"op":0,"doc":"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS","sig":"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU","previous":[]}]},""]
+[{"did":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","did_requested":"did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","doc":{"doc":{"simple":"example"},"key":"z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ:z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB","log":"zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe"},"log":[{"ts":1641224736,"op":2,"doc":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","sig":"z3Kb5qeReCqr3ftxpf2i5UypUwrzrVkyspMtaDcb6e9YdHVSptcAFgvwbgk3qWqspTcGiKDYKXZZh8g6XyM2WPmNp","previous":[]},{"ts":1641224736,"op":0,"doc":"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS","sig":"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU","previous":[]}],"doc_log_id":0,"termination_log_id":1,"error":0,"message":"","verification":"identifier: zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh\n✅ is hash of DID Document:\n{\n  \"doc\": {\n    \"simple\": \"example\"\n  },\n  \"key\": \"z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ:z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB\",\n  \"log\": \"zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe\"\n}\n(Details: https://ownyourdata.github.io/oydid/#calculate_hash)\n\n'log' reference in DID Document: zQmVwMvovLy5KNYHHVHQ1wv8J7y9L6UPE8eyU4tzypFWtYe\n✅ is hash of TERMINATE log record:\n{\n  \"ts\": 1641224736,\n  \"op\": 0,\n  \"doc\": \"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS\",\n  \"sig\": \"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU\",\n  \"previous\": []\n}\n(Details: https://ownyourdata.github.io/oydid/#calculate_hash)\n\nRevocation reference in log record: zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS\n✅ cannot find revocation record searching at\n- https://oydid.ownyourdata.eu\n(Details: https://ownyourdata.github.io/oydid/#retrieve_log)\n\n","full_log":[{"ts":1641224736,"op":2,"doc":"zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh","sig":"z3Kb5qeReCqr3ftxpf2i5UypUwrzrVkyspMtaDcb6e9YdHVSptcAFgvwbgk3qWqspTcGiKDYKXZZh8g6XyM2WPmNp","previous":[]},{"ts":1641224736,"op":0,"doc":"zQmT8SG7a238bF7wdV7LdrEAQpimqhKGor7CQsjtCYdZdTS","sig":"z63hu8LseptBrvB2kEDwhPP35sBj7JDDJsEDW85cjRkrjjac9ZV3HxPW9NVKewHcQYwrVLVsnDCcm1RjbEARE5rJU","previous":[]}]},""]

data/spec/oydid_spec.rb

@@ -584,4 +584,278 @@ describe "OYDID handling" do
     end
   end
 
+  # Identifiers of the published versions of a DID. Every update mints a new
+  # one, so a resolver has to be able to say which is current and which are
+  # earlier - didDocumentMetadata canonicalId and equivalentId.
+  describe "version_ids" do
+    let(:first_did)  { "zQmSE1hzumtZ7AoK1qhHf4t5kiKsujMsJSHqoXtWrdd7K7W" }
+    let(:second_did) { "zQmfEb3KgYZjZUPLTHPmFPdcV6peF5itB5NmJ9N6gaxxE8K" }
+
+    it "reports a freshly created DID as canonical without equivalents" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:" + first_did,
+        "log" => [{ "op" => 2, "doc" => first_did },
+                  { "op" => 0, "doc" => "terminate" }])
+      expect(canonical).to eq "did:oyd:" + first_did
+      expect(equivalent).to eq []
+    end
+
+    it "names the current version canonical and the previous one equivalent" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:" + second_did,
+        "log" => [{ "op" => 1, "doc" => "revoke" },
+                  { "op" => 2, "doc" => first_did },
+                  { "op" => 3, "doc" => second_did },
+                  { "op" => 0, "doc" => "terminate" }])
+      expect(canonical).to eq "did:oyd:" + second_did
+      expect(equivalent).to eq ["did:oyd:" + first_did]
+    end
+
+    it "keeps every earlier version, oldest first" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "did:oyd:zC",
+        "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:zB"]
+    end
+
+    it "adds the method prefix when the resolved DID carries none" do
+      canonical, = Oydid.version_ids("did" => second_did, "log" => [])
+      expect(canonical).to eq "did:oyd:" + second_did
+    end
+
+    # 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
+      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
+
+    it "tolerates a missing log" do
+      canonical, equivalent = Oydid.version_ids("did" => "did:oyd:" + second_did)
+      expect(canonical).to eq "did:oyd:" + second_did
+      expect(equivalent).to eq []
+    end
+
+    # w3c builds alsoKnownAs from the same list. The two used to be computed
+    # separately in three places and drifted apart; this guards the merge.
+    #
+    # The canonical DID has to be one this suite stubs: w3c looks up delegation
+    # keys for it, and WebMock::NetConnectNotAllowedError descends from Exception
+    # rather than StandardError, so the inline `rescue []` around
+    # getDelegatedPubKeysFromDID does not catch it. Only the canonical DID is
+    # fetched - log entries are read, not resolved.
+    it "agrees with the alsoKnownAs the DID document carries" do
+      stubbed_did = "zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh"
+      did_info = {
+        "did" => "did:oyd:" + stubbed_did,
+        "doc" => { "doc" => { "hello" => "world" },
+                   "key" => "z6MktULudTtAsAhRegYPiZ6631RV3viv12qd4GQF8z1xB22S:" \
+                            "z6MkqGC3nWZhYieEVTVDKW5v588CiGfsDSmRVG9ZwwWTvLSK" },
+        "log" => [{ "op" => 2, "doc" => first_did },
+                  { "op" => 3, "doc" => stubbed_did }]
+      }
+      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, 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
+
+  # Which identifier a resolved DID document announces as its own. An update
+  # mints a new did:oyd, but the identifier a relying party holds is the one it
+  # asked for - that is the one the document has to carry.
+  describe "document_id" do
+    let(:first_did)  { "zQmSE1hzumtZ7AoK1qhHf4t5kiKsujMsJSHqoXtWrdd7K7W" }
+    let(:second_did) { "zQmfEb3KgYZjZUPLTHPmFPdcV6peF5itB5NmJ9N6gaxxE8K" }
+    # a DID this suite stubs - w3c looks up delegation keys for whatever it
+    # emits as id, see the note on the alsoKnownAs example above
+    let(:stubbed_did) { "zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh" }
+
+    it "answers with the requested DID when the resolver kept it" do
+      expect(Oydid.document_id("did" => "did:oyd:" + second_did,
+                               "did_requested" => "did:oyd:" + first_did))
+        .to eq "did:oyd:" + first_did
+    end
+
+    it "falls back to the resolved DID for a did_info built by hand" do
+      expect(Oydid.document_id("did" => "did:oyd:" + second_did))
+        .to eq "did:oyd:" + second_did
+    end
+
+    it "adds the method prefix and percent-encodes a location suffix" do
+      expect(Oydid.document_id("did" => "", "did_requested" => first_did + "@https://example.org"))
+        .to eq "did:oyd:" + first_did + "%40example.org"
+    end
+
+    # the point of the exercise: a DID printed on a data carrier keeps naming
+    # itself after an update, while the current version stays readable
+    it "keeps the requested DID as id and moves the current one to alsoKnownAs" do
+      did_info = {
+        "did" => "did:oyd:" + second_did,
+        "did_requested" => "did:oyd:" + stubbed_did,
+        "doc" => { "doc" => { "hello" => "world" },
+                   "key" => "z6MktULudTtAsAhRegYPiZ6631RV3viv12qd4GQF8z1xB22S:" \
+                            "z6MkqGC3nWZhYieEVTVDKW5v588CiGfsDSmRVG9ZwwWTvLSK" },
+        "log" => [{ "op" => 2, "doc" => stubbed_did },
+                  { "op" => 3, "doc" => second_did }]
+      }
+      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:" + second_did]
+      # the entries of verificationMethod are built as hash literals with
+      # "id": - Ruby makes that a symbol key, the surrounding keys are strings
+      expect(wd["verificationMethod"].first[:id]).to start_with("did:oyd:" + stubbed_did + "#")
+      expect(wd["verificationMethod"].first[:controller]).to eq "did:oyd:" + stubbed_did
+
+      # canonicalId still names the version the log resolves to, and the
+      # equivalent list is everything the document does not call itself
+      canonical, equivalent = Oydid.version_ids(did_info)
+      expect(canonical).to eq "did:oyd:" + second_did
+      expect(equivalent).to eq ["did:oyd:" + second_did]
+    end
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: oydid
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  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