oydid 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66decf23cb4e474d0703a8948e20474be619c05083bd8abd5ab8d45857ac4ac0
-  data.tar.gz: db83f3c7ba0a20c5e4f8fd8ba8b9977b42b9b78fc56ad11df8a8bf12e9657704
+  metadata.gz: d3e561caa744ec1b341317d142b27f5b9d7d9dddf92b2d18aaf2117fff05cb9a
+  data.tar.gz: 6aa242687b1765148f79e9b6911d22e81339159f2f0c45445c0be1ce804fe0ad
 SHA512:
-  metadata.gz: 8856635688f0dd47b246443d7fcc7a994ceef87e7d2594530da0f3489445a544f3c7cc9d20327fec7da3988e83872d1ddf3c854bd4db25b367b72fa917ba09c3
-  data.tar.gz: '08956cf2da8ed63a35261a7ffa01cb58b11a177c77fe8b5f873f8ed4d59592695c0e80bd72d118c28f4266728b10e420b4eaab7189c406dd6c7731e52f40e38d'
+  metadata.gz: 35d735d7f16edf812645b91034b5c8824437144fb86b2dba19e2b165a1912279fc3e6b09916cde37004402bb309f5faad7248105b41de07f293892f7e6963d09
+  data.tar.gz: 0e333ede2a2b46e9c6264264f638cf3b54823cab9663a11af3bf776f796965210abb39b3c37555d0824f67d9b55506d3065803b1a94182097acdf0b11b9c670e

data/VERSION

@@ -1 +1 @@
-0.8.2
+0.9.0

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,61 @@ 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.
+    #
+    # 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
+        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
+                    equivalentIds << eid
+                end
+            end
+        end unless did_info["log"].nil?
+        [canonical, equivalentIds]
+    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 +1496,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 +1627,13 @@ 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.
+        equivalentIds = version_ids(did_info).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,139 @@ 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
+
+    it "percent-encodes a location suffix" do
+      canonical, equivalent = Oydid.version_ids(
+        "did" => "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(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).last
+    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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oydid
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Christoph Fabianek