feat(pairing): expose ownership API

expose ownserhip api, save voucher and key into the db (with ttl)
link the related device to the voucher

Signed-off-by: Eddy Babetto <eddy.babetto@secomind.com>

Author: eddbbt

apps/astarte_pairing/lib/astarte_pairing/fdo/voucher_manager.ex

@@ -0,0 +1,73 @@
+#
+# This file is part of Astarte.
+#
+# Copyright 2025 SECO Mind Srl
+#
+# 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.
+#
+
+defmodule Astarte.Pairing.FDO.VoucherManager do
+  alias Astarte.Pairing.Queries
+  require Logger
+
+  def save_voucher(realm_name, voucher_blob, pkey_blob) do
+    with {:ok, inserted_voucher} <-
+           Queries.create_ownership_voucher(realm_name, voucher_blob, pkey_blob),
+         device_guuid <- extract_device_guuid_from_voucher_data(voucher_blob),
+         {:ok, _} <-
+           Queries.update_device_registration_voucher(
+             realm_name,
+             device_guuid,
+             inserted_voucher.id
+           ) do
+      :ok
+    end
+  end
+
+  defp extract_device_guuid_from_voucher_data(voucher_blob) do
+    with {:ok, cbor_data} <- clean_and_b64_decode_voucher_blob(voucher_blob),
+         {:ok, decoded_voucher, _rest} <- cbor_data |> CBOR.decode(),
+         {:ok, decoded_header, _rest} <- extract_and_decode_voucher_header(decoded_voucher),
+         device_guid_binary <- device_id_from_header(decoded_header) do
+      UUID.binary_to_string!(device_guid_binary)
+    else
+      error ->
+        "error extracting device guid from ownership voucher: #{inspect(error)}"
+        |> Logger.error()
+
+        error
+    end
+  end
+
+  defp clean_and_b64_decode_voucher_blob(voucher_blob) do
+    ov_data =
+      voucher_blob
+      |> String.replace("-----BEGIN OWNERSHIP VOUCHER-----", "")
+      |> String.replace("-----END OWNERSHIP VOUCHER-----", "")
+      |> String.replace(~r/\s/, "")
+
+    with {:ok, cbor_data} <- Base.decode64(ov_data) do
+      {:ok, cbor_data}
+    end
+  end
+
+  defp extract_and_decode_voucher_header(decoded_voucher) do
+    decoded_voucher |> Enum.at(1) |> Map.fetch!(:value) |> CBOR.decode()
+  end
+
+  defp device_id_from_header(decoded_header) do
+    decoded_header
+    |> Enum.at(1)
+    |> Map.fetch!(:value)
+  end
+end

apps/astarte_pairing/lib/astarte_pairing/queries.ex

@@ -28,6 +28,7 @@ defmodule Astarte.Pairing.Queries do
   alias Astarte.DataAccess.KvStore
   alias Astarte.DataAccess.Realms.Realm
   alias Astarte.DataAccess.Repo
+  alias Astarte.DataAccess.FDO.OwnershipVoucher
 
   require Logger
 
@@ -223,6 +224,33 @@ defmodule Astarte.Pairing.Queries do
     {:ok, count}
   end
 
+  def create_ownership_voucher(realm_name, voucher_blob, pkey_blob) do
+    keyspace_name = Realm.keyspace_name(realm_name)
+    opts = [prefix: keyspace_name, consistency: Consistency.device_info(:write)]
+
+    timestamp_ms =
+      DateTime.utc_now()
+      |> DateTime.add(7, :day)
+      |> DateTime.to_unix(:millisecond)
+
+    %OwnershipVoucher{
+      voucher_data: voucher_blob,
+      private_key: pkey_blob,
+      expiry: timestamp_ms
+    }
+    |> Repo.insert(opts)
+  end
+
+  def update_device_registration_voucher(realm_name, device_id, voucher_id) do
+    keyspace_name = Realm.keyspace_name(realm_name)
+
+    %Device{
+      device_id: device_id,
+      ownership_voucher: voucher_id
+    }
+    |> Repo.insert(prefix: keyspace_name, consistency: Consistency.device_info(:write))
+  end
+
   defp do_register_device(
          realm_name,
          device_id,

apps/astarte_pairing/lib/astarte_pairing_web/controllers/ownership_voucher_controller.ex

@@ -0,0 +1,36 @@
+#
+# This file is part of Astarte.
+#
+# Copyright 2025 SECO Mind Srl
+#
+# 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.
+#
+
+defmodule Astarte.PairingWeb.OwnershipVoucherController do
+  use Astarte.PairingWeb, :controller
+
+  alias Astarte.Pairing.FDO.VoucherManager
+
+  action_fallback Astarte.PairingWeb.FallbackController
+
+  def create(conn, %{
+        "ownership_voucher" => voucher,
+        "private_key" => key,
+        "realm_name" => realm_name
+      }) do
+    with :ok <- VoucherManager.save_voucher(realm_name, voucher, key) do
+      conn
+      |> send_resp(200, "")
+    end
+  end
+end

apps/astarte_pairing/lib/astarte_pairing_web/router.ex

@@ -38,6 +38,11 @@ defmodule Astarte.PairingWeb.Router do
 
     get "/version", VersionController, :show
 
+    scope "/ownership-voucher" do
+      pipe_through :agent_api
+      post "/", OwnershipVoucherController, :create
+    end
+
     scope "/agent" do
       pipe_through :agent_api
 

apps/astarte_pairing/mix.exs

@@ -119,7 +119,8 @@ defmodule Astarte.Pairing.Mixfile do
       {:mimic, "~> 1.11", only: :test},
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
       {:con_cache, "~> 1.1"},
-      {:astarte_events, path: astarte_lib("astarte_events")}
+      {:astarte_events, path: astarte_lib("astarte_events")},
+      {:cbor, "~> 1.0"}
     ]
   end
 

apps/astarte_pairing/mix.lock

@@ -7,6 +7,7 @@
   "bcrypt_elixir": {:hex, :bcrypt_elixir, "2.3.1", "5114d780459a04f2b4aeef52307de23de961b69e13a5cd98a911e39fda13f420", [:make, :mix], [{:comeonin, "~> 5.3", [hex: :comeonin, repo: "hexpm", optional: false]}, {:elixir_make, "~> 0.6", [hex: :elixir_make, repo: "hexpm", optional: false]}], "hexpm", "42182d5f46764def15bf9af83739e3bf4ad22661b1c34fc3e88558efced07279"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
   "castore": {:hex, :castore, "1.0.15", "8aa930c890fe18b6fe0a0cff27b27d0d4d231867897bd23ea772dee561f032a3", [:mix], [], "hexpm", "96ce4c69d7d5d7a0761420ef743e2f4096253931a3ba69e5ff8ef1844fe446d3"},
+  "cbor": {:hex, :cbor, "1.0.1", "39511158e8ea5a57c1fcb9639aaa7efde67129678fee49ebbda780f6f24959b0", [:mix], [], "hexpm", "5431acbe7a7908f17f6a9cd43311002836a34a8ab01876918d8cfb709cd8b6a2"},
   "certifi": {:hex, :certifi, "2.9.0", "6f2a475689dd47f19fb74334859d460a2dc4e3252a3324bd2111b8f0429e7e21", [:rebar3], [], "hexpm", "266da46bdb06d6c6d35fde799bcb28d36d985d424ad7c08b5bb48f5b5cdd4641"},
   "cfxxl": {:git, "https://github.com/ispirata/cfxxl.git", "98dc50b1cfe5a682b051b38b83cebc644bc08488", []},
   "combine": {:hex, :combine, "0.10.0", "eff8224eeb56498a2af13011d142c5e7997a80c8f5b97c499f84c841032e429f", [:mix], [], "hexpm", "1b1dbc1790073076580d0d1d64e42eae2366583e7aecd455d1215b0d16f2451b"},