RFC: thinking out loud about signed-by field to accompany git: urls

src/client/opamAction.ml

@@ -459,6 +459,7 @@ let prepare_package_source st nv dir =
         (OpamPackage.to_string nv ^ "/" ^ OpamFilename.Base.to_string basename)
         (OpamFilename.create dir basename)
         (OpamFile.URL.checksum urlf)
+        (OpamFile.URL.signed_by urlf)
         (OpamFile.URL.url urlf :: OpamFile.URL.mirrors urlf)
       @@| function
       | Result () | Up_to_date () -> None

src/client/opamAdminCommand.ml

@@ -157,6 +157,9 @@ let package_files_to_cache repo_root cache_dir cache_urls
       let checksums =
         OpamHash.sort (OpamFile.URL.checksum urlf)
       in
+      let signed_by =
+        OpamSignature.sort (OpamFile.URL.signed_by urlf)
+      in
       match checksums with
       | [] ->
         OpamConsole.warning "[%s] no checksum, not caching"
@@ -172,7 +175,7 @@ let package_files_to_cache repo_root cache_dir cache_urls
           else
             OpamRepository.pull_file_to_cache label
               ~cache_urls ~cache_dir
-              checksums
+              checksums signed_by
               (OpamFile.URL.url urlf :: OpamFile.URL.mirrors urlf)
             @@| fun r -> match OpamRepository.report_fetch_result nv r with
             | Not_available (_,m) -> Some m
@@ -603,7 +606,7 @@ let add_hashes_command cli =
       hash_tables
   in
   let additions_count = ref 0 in
-  let get_hash hash_tables ~cache_urls ~cache_dir kind known_hashes url =
+  let get_hash hash_tables ~cache_urls ~cache_dir kind known_hashes signed_by url =
     let found =
       List.fold_left (fun result hash ->
           match result with
@@ -625,7 +628,7 @@ let add_hashes_command cli =
           (fun () ->
              OpamRepository.pull_file (OpamUrl.to_string url)
                ~cache_dir ~cache_urls
-               f known_hashes [url]
+               f known_hashes signed_by [url]
              @@| function
              | Result () | Up_to_date () ->
                OpamHash.compute ~kind (OpamFilename.to_string f)
@@ -669,6 +672,7 @@ let add_hashes_command cli =
             else has_error
           in
           let process_url has_error urlf =
+            let signed_by = OpamFile.URL.signed_by urlf in
             let hashes = OpamFile.URL.checksum urlf in
             let hashes =
               if replace then
@@ -683,7 +687,7 @@ let add_hashes_command cli =
                   if List.exists (fun h -> OpamHash.kind h = kind) hashes
                   then has_error, hashes else
                     match get_hash hash_tables ~cache_urls ~cache_dir kind
-                            hashes (OpamFile.URL.url urlf) with
+                            hashes signed_by (OpamFile.URL.url urlf) with
                     | Some h -> has_error, hashes @ [h]
                     | None ->
                       OpamConsole.error "Could not get hash for %s: %s"

src/client/opamCommands.ml

@@ -3410,7 +3410,7 @@ let pin ?(unpin_only=false) cli =
           OpamRepository.pull_tree
             ~cache_dir:(OpamRepositoryPath.download_cache
                           OpamStateConfig.(!r.root_dir))
-            basename pin_cache_dir [] [url] @@| function
+            basename pin_cache_dir [] [] [url] @@| function
           | Not_available (_,u) ->
             OpamConsole.error_and_exit `Sync_error
               "Could not retrieve %s" u
@@ -3798,7 +3798,7 @@ let source cli =
                   ~cache_dir:(OpamRepositoryPath.download_cache
                                 OpamStateConfig.(!r.root_dir))
                   ?subpath
-                  (OpamPackage.to_string nv) dir []
+                  (OpamPackage.to_string nv) dir [] []
                   [url])
            with
            | Not_available (_,u) ->

src/client/opamPinCommand.ml

@@ -377,7 +377,7 @@ let fetch_all_pins st ?working_dir pins =
       let name = OpamPackage.Name.to_string name in
       OpamProcess.Job.Op.(
         OpamRepository.pull_tree ~cache_dir ?subpath ?working_dir
-          name srcdir [] [url]
+          name srcdir [] [] [url]
         @@| fun r -> (pinned, r))
     in
     OpamParallel.map ~jobs:OpamStateConfig.(!r.dl_jobs) ~command pins
@@ -832,7 +832,7 @@ let scan ~normalise ~recurse ?subpath url =
         OpamRepository.pull_tree
           ~cache_dir:(OpamRepositoryPath.download_cache
                         OpamStateConfig.(!r.root_dir))
-          basename pin_cache_dir [] [url] @@| function
+          basename pin_cache_dir [] [] [url] @@| function
         | Not_available (_,u) ->
           OpamConsole.error_and_exit `Sync_error
             "Could not retrieve %s" u

src/core/opamSignature.ml

@@ -0,0 +1,105 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright 2025 ahrefs                                               *)
+(*                                                                        *)
+(*  All rights reserved. This file is distributed under the terms of the  *)
+(*  GNU Lesser General Public License version 2.1, with the special       *)
+(*  exception on linking described in the file LICENSE.                   *)
+(*                                                                        *)
+(**************************************************************************)
+
+(* TODO: proper "kind" (cypher+bitlength? sigstore uris?) *)
+type kind = [ `GPG ]
+
+let _default_kind = `GPG
+let all_kinds = [`GPG]
+
+type t = kind * string
+
+let kind = fst
+let contents = snd
+
+(* Order by signature strength *)
+let compare_kind k l =
+  match k, l with
+  | `GPG, `GPG -> 0
+
+let equal_kind k1 k2 = compare_kind k1 k2 = 0
+
+let compare (k,h) (l,i) =
+  match compare_kind k l with
+  | 0 -> String.compare h i
+  | cmp -> cmp
+
+let equal h h' = compare h h' = 0
+
+let pfx_sep_char = '='
+let pfx_sep_str = String.make 1 pfx_sep_char
+
+let string_of_kind = function
+  | `GPG -> "gpg"
+
+let kind_of_string s = match String.lowercase_ascii s with
+  | "gpg" -> `GPG
+  | _ -> invalid_arg "OpamSignature.kind_of_string"
+
+let is_hex_str len s =
+  String.length s = len && OpamStd.String.is_hex s
+
+let len = function
+  | `GPG -> 16 (* dummy summy *)
+
+let valid kind = is_hex_str (len kind)
+
+let is_null h =
+  let count_not_zero c =
+    function '0' -> c | _ -> succ c
+  in
+  OpamCompat.String.fold_left count_not_zero 0 (contents h) <> 0
+
+let make kind s =
+  if valid kind s then kind, String.lowercase_ascii s
+  else invalid_arg ("OpamSignature.make_"^string_of_kind kind)
+
+let gpg = make `GPG
+
+let of_string_opt s =
+  try
+      match OpamStd.String.cut_at s pfx_sep_char with
+      | None -> None
+      | Some (skind, s) ->
+          let kind = kind_of_string skind in
+          if valid kind s then Some (kind, String.lowercase_ascii s)
+          else None
+  with Invalid_argument _ -> None
+
+let of_string s =
+  match of_string_opt s with
+  | Some h -> h
+  | None -> invalid_arg "OpamSignature.of_string"
+
+let to_string (kind,s) =
+  String.concat pfx_sep_str [string_of_kind kind; s]
+
+let to_json s = `String (to_string s)
+let of_json = function
+| `String s -> of_string_opt s
+| _ -> None
+
+let sort signatures =
+  List.sort (fun h h' -> compare h' h) signatures
+
+let check_commit `TODO (_kind, _k) = failwith "TODO"
+
+module O = struct
+  type _t = t
+  type t = _t
+  let to_string = to_string
+  let to_json = to_json
+  let of_json = of_json
+  let compare = compare
+end
+
+module Set = OpamStd.Set.Make(O)
+
+module Map = OpamStd.Map.Make(O)

src/core/opamSignature.mli

@@ -0,0 +1,40 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright 2025 ahrefs                                               *)
+(*                                                                        *)
+(*  All rights reserved. This file is distributed under the terms of the  *)
+(*  GNU Lesser General Public License version 2.1, with the special       *)
+(*  exception on linking described in the file LICENSE.                   *)
+(*                                                                        *)
+(**************************************************************************)
+
+(* GPG, as supported by git *)
+type kind = [ `GPG ]
+
+type t
+
+val kind: t -> kind
+
+(** The list of all the possible values of kind *)
+val all_kinds : kind list
+
+(** The value of the hash, as a string of hexadecimal characters *)
+val contents: t -> string
+
+val string_of_kind: kind -> string
+
+val gpg: string -> t
+
+include OpamStd.ABSTRACT with type t := t
+
+val of_string_opt: string -> t option
+val compare_kind: kind -> kind -> int
+val equal_kind: kind -> kind -> bool
+
+(** Check if signature contains only 0 *)
+val is_null: t -> bool
+
+(** Sorts the list from strongest to weakest *)
+val sort : t list -> t list
+
+val check_commit: [ `TODO ] -> t -> bool

src/format/opamFile.ml

@@ -2421,34 +2421,38 @@ module URLSyntax = struct
     url     : url;
     mirrors : url list;
     checksum: OpamHash.t list;
+    signed_by: OpamSignature.t list;
     swhid: OpamSWHID.t option;
     errors  : (string * Pp.bad_format) list;
     subpath : subpath option;
   }
 
-  let create ?(mirrors=[]) ?(checksum=[]) ?swhid ?subpath url =
+  let create ?(mirrors=[]) ?(checksum=[]) ?(signed_by=[]) ?swhid ?subpath url =
     {
-      url; mirrors; checksum; swhid; errors = []; subpath;
+      url; mirrors; checksum; signed_by; swhid; errors = []; subpath;
     }
 
   let empty = {
-    url     = OpamUrl.empty;
-    mirrors = [];
-    checksum= [];
-    swhid = None;
-    errors  = [];
-    subpath = None;
+    url      = OpamUrl.empty;
+    mirrors  = [];
+    checksum = [];
+    signed_by= [];
+    swhid    = None;
+    errors   = [];
+    subpath  = None;
   }
 
   let url t = t.url
   let mirrors t = t.mirrors
   let checksum t = t.checksum
+  let signed_by t = t.signed_by
   let swhid t = t.swhid
   let subpath t = t.subpath
 
   let with_url url t = { t with url }
   let with_mirrors mirrors t = { t with mirrors }
   let with_checksum checksum t = { t with checksum = checksum }
+  let with_signed_by signed_by t = { t with signed_by = signed_by }
   let with_swhid swhid t = { t with swhid = Some swhid }
   let with_swhid_opt swhid t = { t with swhid = swhid }
   let with_subpath subpath t = { t with subpath = Some subpath }
@@ -2477,6 +2481,9 @@ module URLSyntax = struct
       "checksum", Pp.ppacc with_checksum checksum
         (Pp.V.map_list ~depth:1
            (Pp.V.string -| Pp.of_module "checksum" (module OpamHash)));
+      "signed_by", Pp.ppacc with_signed_by signed_by
+        (Pp.V.map_list ~depth:1
+           (Pp.V.string -| Pp.of_module "signed_by" (module OpamSignature)));
       "mirrors", Pp.ppacc with_mirrors mirrors
         (Pp.V.map_list ~depth:1 Pp.V.url);
       "subpath", Pp.ppacc_opt

src/format/opamFile.mli

@@ -324,6 +324,7 @@ module URL: sig
 
   val create:
     ?mirrors:url list -> ?checksum:OpamHash.t list ->
+    ?signed_by:OpamSignature.t list ->
     ?swhid:OpamSWHID.t -> ?subpath:subpath ->
     url -> t
 
@@ -335,10 +336,12 @@ module URL: sig
   (** Archive checksum *)
   val checksum: t -> OpamHash.t list
   val swhid: t -> OpamSWHID.t option
+  val signed_by: t -> OpamSignature.t list
 
   (** Constructor *)
   val with_url: url -> t -> t
   val with_checksum: OpamHash.t list -> t -> t
+  val with_signed_by: OpamSignature.t list -> t -> t
   val with_mirrors: OpamUrl.t list -> t -> t
   val with_swhid: OpamSWHID.t -> t -> t
   val with_swhid_opt: OpamSWHID.t option -> t -> t