Init py-peer-record module

Author: lla-dane

libp2p/records/__init__.py

@@ -0,0 +1,23 @@
+syntax = "proto3";
+package record.pb;
+
+option go_package = "github.com/libp2p/go-libp2p-record/pb";
+
+// Record represents a dht record that contains a value
+// for a key value pair
+message Record {
+  // The key that references this record
+  bytes key = 1;
+
+  // The actual value this record is storing
+  bytes value = 2;
+
+  // Note: These fields were removed from the Record message
+  // hash of the authors public key
+  // optional string author = 3;
+  // A PKI signature for the key+value+author
+  // optional bytes signature = 4;
+
+  // Time the record was received, set by receiver
+  string timeReceived = 5;
+}

libp2p/records/pb/record.proto

@@ -0,0 +1,49 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+import builtins
+import google.protobuf.descriptor
+import google.protobuf.message
+import sys
+
+if sys.version_info >= (3, 8):
+    import typing as typing_extensions
+else:
+    import typing_extensions
+
+DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+
+class Record(google.protobuf.message.Message):
+    """Record represents a dht record that contains a value
+    for a key value pair
+    """
+
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    KEY_FIELD_NUMBER: builtins.int
+    VALUE_FIELD_NUMBER: builtins.int
+    TIMERECEIVED_FIELD_NUMBER: builtins.int
+    key: builtins.bytes
+    """The key that references this record"""
+    value: builtins.bytes
+    """The actual value this record is storing"""
+    timeReceived: builtins.str
+    """Note: These fields were removed from the Record message
+    hash of the authors public key
+    optional string author = 3;
+    A PKI signature for the key+value+author
+    optional bytes signature = 4;
+
+    Time the record was received, set by receiver
+    """
+    def __init__(
+        self,
+        *,
+        key: builtins.bytes = ...,
+        value: builtins.bytes = ...,
+        timeReceived: builtins.str = ...,
+    ) -> None: ...
+    def ClearField(self, field_name: typing_extensions.Literal["key", b"key", "timeReceived", b"timeReceived", "value", b"value"]) -> None: ...
+
+global___Record = Record

libp2p/records/pb/record_pb2.py

@@ -0,0 +1,102 @@
+import multihash
+
+from libp2p.crypto.ed25519 import Ed25519PublicKey
+from libp2p.crypto.keys import PublicKey
+from libp2p.crypto.pb import crypto_pb2
+from libp2p.crypto.rsa import RSAPublicKey
+from libp2p.crypto.secp256k1 import Secp256k1PublicKey
+from libp2p.peer.id import ID
+from libp2p.records.utils import InvalidRecordType, split_key
+from libp2p.records.validator import Validator
+
+
+class PublicKeyValidator(Validator):
+    """
+    Validator for public key records.
+    """
+
+    def validate(self, key: str, value: bytes) -> None:
+        """
+        Validate a public key record.
+
+        Args:
+            key (str): The key associated with the record.
+            value (bytes): The value of the record, expected to be a public key.
+
+        Raises:
+            InvalidRecordType: If the namespace is not 'pk', the key
+                is not a valid multihash,
+                the public key cannot be unmarshaled, the peer ID cannot be derived, or
+                the public key does not match the storage key.
+
+        """
+        ns, key = split_key(key)
+        if ns != "pk":
+            raise InvalidRecordType("namespace not 'pk'")
+
+        keyhash = bytes.fromhex(key)
+        try:
+            _ = multihash.decode(keyhash)
+        except Exception:
+            raise InvalidRecordType("key did not contain valid multihash")
+
+        try:
+            pubkey = unmarshal_public_key(value)
+        except Exception:
+            raise InvalidRecordType("Unable to unmarshal public key")
+
+        try:
+            peer_id = ID.from_pubkey(pubkey)
+        except Exception:
+            raise InvalidRecordType("Could not derive peer ID from public key")
+
+        if peer_id.to_bytes() != keyhash:
+            raise InvalidRecordType("public key does not match storage key")
+
+    def select(self, key: str, values: list[bytes]) -> int:
+        """
+        Select a value from a list of public key records.
+
+        Args:
+            key (str): The key associated with the records.
+            values (list[bytes]): A list of public key values.
+
+        Returns:
+            int: Always returns 0 as all public keys are treated identically.
+
+        """
+        return 0  # All public keys are treated identical
+
+
+def unmarshal_public_key(data: bytes) -> PublicKey:
+    """
+    Deserialize a public key from its serialized byte representation.
+    This function takes a byte sequence representing a serialized public key
+    and reconstructs the corresponding `PublicKey` object based on its type.
+
+    Args:
+        data (bytes): The serialized byte representation of the public key.
+
+    Returns:
+        PublicKey: The deserialized public key object.
+
+    Raises:
+        ValueError: If the key type is unsupported or unrecognized.
+    Supported Key Types:
+        - RSA
+        - Ed25519
+        - Secp256k1
+
+    """
+    proto_key = crypto_pb2.PublicKey.FromString(data)
+    key_type = proto_key.key_type
+    key_data = proto_key.data
+
+    if key_type == crypto_pb2.KeyType.RSA:
+        return RSAPublicKey.from_bytes(key_data)
+    elif key_type == crypto_pb2.KeyType.Ed25519:
+        return Ed25519PublicKey.from_bytes(key_data)
+    elif key_type == crypto_pb2.KeyType.Secp256k1:
+        return Secp256k1PublicKey.from_bytes(key_data)
+    else:
+        raise ValueError(f"Unsupported key type: {key_type}")

libp2p/records/pb/record_pb2.pyi

@@ -0,0 +1,19 @@
+from libp2p.records.pb import record_pb2
+
+
+def make_put_record(key: str, value: bytes) -> record_pb2.Record:
+    """
+    Create a new Record object with the specified key and value.
+
+    Args:
+        key (str): The key for the record, which will be encoded as bytes.
+        value (bytes): The value to associate with the key in the record.
+
+    Returns:
+        record_pb2.Record: A Record object containing the provided key and value.
+
+    """
+    record = record_pb2.Record()
+    record.key = key.encode()
+    record.value = value
+    return record

libp2p/records/pubkey.py

@@ -0,0 +1,27 @@
+class InvalidRecordType(Exception):
+    pass
+
+
+def split_key(key: str) -> tuple[str, str]:
+    """
+    Split a record key into its type and the rest. The key must start with
+    '/' and contain another '/' to separate the type. Raises `InvalidRecordType`
+    if the key is invalid.
+
+    Args:
+        key (str): The record key to split.
+
+    Returns:
+        tuple[str, str]: The key type and the rest.
+
+    """
+    if not key or key[0] != "/":
+        raise InvalidRecordType("Invalid record keytype")
+
+    key = key[1:]
+
+    i = key.find("/")
+    if i <= 0:
+        raise InvalidRecordType("Invalid record keytype")
+
+    return key[:i], key[i + 1 :]

libp2p/records/record.py

@@ -0,0 +1,85 @@
+from libp2p.records.utils import InvalidRecordType, split_key
+
+
+class ErrBetterRecord(Exception):
+    def __init__(self, key: str, value: bytes):
+        self.key = key
+        self.value = value
+        super().__init__(f'Found better value for "{key}')
+
+
+class Validator:
+    """Base class for all validators"""
+
+    def validate(self, key: str, value: bytes) -> None:
+        raise NotImplementedError
+
+    def select(self, key: str, values: list[bytes]) -> int:
+        raise NotImplementedError
+
+
+class NamespacedValidator:
+    """
+    Manages a collection of validators, each associated with a specific namespace.
+    """
+
+    def __init__(self, validators: dict[str, Validator]):
+        self._validators = validators
+
+    def validator_by_key(self, key: str) -> Validator | None:
+        """
+        Retrieve the validator responsible for the given key's namespace.
+
+        Args:
+            key (str): A namespaced key in the form "namespace/value".
+
+        Returns:
+            Optional[Validator]: The matching validator, or None if not found.
+
+        """
+        try:
+            ns, _ = split_key(key)
+        except InvalidRecordType:
+            return None
+        return self._validators.get(ns)
+
+    def validate(self, key: str, value: bytes) -> None:
+        """
+        Validate a key-value pair using the appropriate namespaced validator.
+
+        Args:
+            key (str): The namespaced key (e.g., "pk/Qm...").
+            value (bytes): The value to be validated.
+
+        Raises:
+            InvalidRecordType: If no matching validator is found.
+            Exception: Propagates any exception raised by the sub-validator.
+
+        """
+        validator = self.validator_by_key(key)
+        if validator is None:
+            raise InvalidRecordType("Invalid record keytype")
+        return validator.validate(key, value)
+
+    def select(self, key: str, values: list[bytes]) -> int:
+        """
+        Choose the best value from a list using the namespaced validator.
+
+        Args:
+            key (str): The namespaced key used to find the validator.
+            values (List[bytes]): List of candidate values to choose from.
+
+        Returns:
+            int: Index of the selected best value in the input list.
+
+        Raises:
+            ValueError: If the values list is empty.
+            InvalidRecordType: If no matching validator is found.
+
+        """
+        if not values:
+            raise ValueError("Can't select from empty value list")
+        validator = self.validator_by_key(key)
+        if validator is None:
+            raise InvalidRecordType("Invalid record keytype")
+        return validator.select(key, values)