sci-protocol 0.2.0__py3-none-any.whl

pysci/keys.py

@@ -0,0 +1,247 @@
+"""Ed25519 public JWKs (RFC 8037) and key file helpers (§5.1)."""
+
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass
+from typing import Final
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from .ed25519 import check_public_key_point
+from .errors import Invalid, Issue, IssueCollector
+from .jsonstrict import json_type_name
+
+__all__ = [
+    "PublicKey",
+    "generate_private_key",
+    "load_private_key_pem",
+    "load_public_key_pem",
+    "looks_like_private_key",
+    "parse_public_jwk",
+    "private_key_to_pem",
+    "public_key_of",
+    "x_to_bytes",
+]
+
+_X_PATTERN: Final = re.compile(r"[A-Za-z0-9_-]{43}")
+
+
+def x_to_bytes(x: str) -> bytes | None:
+    """Decode a canonical unpadded base64url ``x``; None if noncanonical."""
+    if not _X_PATTERN.fullmatch(x):
+        return None
+    raw = base64.urlsafe_b64decode(x + "=")
+    if base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") != x:
+        return None
+    return raw
+
+
+@dataclass(frozen=True, slots=True)
+class PublicKey:
+    """An Ed25519 public key; ``raw`` holds the 32 encoded bytes."""
+
+    raw: bytes
+
+    def __post_init__(self) -> None:
+        if len(self.raw) != 32:
+            raise ValueError("Ed25519 public keys are 32 bytes")
+
+    @property
+    def x(self) -> str:
+        """Canonical unpadded base64url JWK ``x`` value."""
+        return base64.urlsafe_b64encode(self.raw).rstrip(b"=").decode("ascii")
+
+    def to_jwk(self) -> dict[str, str]:
+        """The public JWK object with exactly ``kty``, ``crv``, and ``x``."""
+        return {"kty": "OKP", "crv": "Ed25519", "x": self.x}
+
+    @classmethod
+    def from_x(cls, x: str) -> PublicKey:
+        """Parse a canonical ``x`` value. Raises :class:`Invalid`."""
+        raw = x_to_bytes(x)
+        if raw is None:
+            raise Invalid(
+                Issue(
+                    "jwk_x_encoding",
+                    "x must be canonical unpadded base64url of 32 bytes",
+                    section="5.1",
+                    observed=x,
+                )
+            )
+        return cls(raw)
+
+    def to_pem(self) -> bytes:
+        """SubjectPublicKeyInfo PEM encoding."""
+        return Ed25519PublicKey.from_public_bytes(self.raw).public_bytes(
+            serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+
+    def to_cryptography(self) -> Ed25519PublicKey:
+        return Ed25519PublicKey.from_public_bytes(self.raw)
+
+
+def parse_public_jwk(
+    value: object,
+    *,
+    file: str | None = None,
+    field: str = "/public_key",
+    collector: IssueCollector | None = None,
+    check_point: bool = True,
+) -> PublicKey | None:
+    """Validate a public JWK under §5.1.
+
+    With a ``collector`` issues are appended and None is returned on failure;
+    without one the first failure raises :class:`Invalid`.
+    """
+    local = IssueCollector()
+    result = _parse_jwk(value, file, field, local, check_point)
+    if collector is not None:
+        collector.extend(local.issues)
+        return result
+    local.raise_if_any()
+    return result
+
+
+def _parse_jwk(
+    value: object, file: str | None, field: str, issues: IssueCollector, check_point: bool
+) -> PublicKey | None:
+    if not isinstance(value, dict):
+        issues.add(
+            "jwk_type",
+            "public key must be a JWK object",
+            section="5.1",
+            file=file,
+            field=field,
+            observed=json_type_name(value),
+        )
+        return None
+    extra = sorted(set(value) - {"kty", "crv", "x"})
+    missing = sorted({"kty", "crv", "x"} - set(value))
+    if extra:
+        issues.add(
+            "jwk_fields",
+            "only kty, crv, and x are permitted in a public key",
+            section="5.1",
+            file=file,
+            field=field,
+            observed=extra,
+        )
+    if missing:
+        issues.add(
+            "jwk_fields",
+            "public key requires kty, crv, and x",
+            section="5.1",
+            file=file,
+            field=field,
+            observed=missing,
+        )
+    if "kty" in value and value["kty"] != "OKP":
+        issues.add(
+            "jwk_kty",
+            'kty must be "OKP"',
+            section="5.1",
+            file=file,
+            field=field + "/kty",
+            observed=value["kty"],
+        )
+    if "crv" in value and value["crv"] != "Ed25519":
+        issues.add(
+            "jwk_crv",
+            'crv must be "Ed25519"',
+            section="5.1",
+            file=file,
+            field=field + "/crv",
+            observed=value["crv"],
+        )
+    x = value.get("x")
+    raw: bytes | None = None
+    if "x" in value:
+        raw = x_to_bytes(x) if isinstance(x, str) else None
+        if raw is None:
+            issues.add(
+                "jwk_x_encoding",
+                "x must be canonical unpadded base64url of 32 bytes",
+                section="5.1",
+                file=file,
+                field=field + "/x",
+                observed=x,
+            )
+    if issues or raw is None:
+        return None
+    if check_point:
+        try:
+            check_public_key_point(raw, file=file)
+        except Invalid as exc:
+            issues.extend(exc.issues)
+            return None
+    return PublicKey(raw)
+
+
+def generate_private_key() -> Ed25519PrivateKey:
+    """Create a new Ed25519 private key."""
+    return Ed25519PrivateKey.generate()
+
+
+def public_key_of(private_key: Ed25519PrivateKey) -> PublicKey:
+    """The :class:`PublicKey` matching ``private_key``."""
+    return PublicKey(
+        private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+    )
+
+
+def private_key_to_pem(private_key: Ed25519PrivateKey, password: bytes | None = None) -> bytes:
+    """PKCS#8 PEM, optionally encrypted with ``password``."""
+    encryption: serialization.KeySerializationEncryption = (
+        serialization.BestAvailableEncryption(password)
+        if password
+        else serialization.NoEncryption()
+    )
+    return private_key.private_bytes(
+        serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, encryption
+    )
+
+
+def load_private_key_pem(data: bytes, password: bytes | None = None) -> Ed25519PrivateKey:
+    """Load a PKCS#8 PEM Ed25519 private key. Raises ValueError for other key types."""
+    key = serialization.load_pem_private_key(data, password=password)
+    if not isinstance(key, Ed25519PrivateKey):
+        raise ValueError("not an Ed25519 private key")
+    return key
+
+
+def load_public_key_pem(data: bytes) -> PublicKey:
+    """Load a SubjectPublicKeyInfo PEM Ed25519 public key."""
+    key = serialization.load_pem_public_key(data)
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError("not an Ed25519 public key")
+    return PublicKey(key.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw))
+
+
+_PRIVATE_MARKERS: Final = (
+    b"-----BEGIN PRIVATE KEY-----",
+    b"-----BEGIN ENCRYPTED PRIVATE KEY-----",
+    b"-----BEGIN OPENSSH PRIVATE KEY-----",
+    b"-----BEGIN RSA PRIVATE KEY-----",
+    b"-----BEGIN EC PRIVATE KEY-----",
+    b"-----BEGIN DSA PRIVATE KEY-----",
+    b"PuTTY-User-Key-File-",
+)
+
+
+def looks_like_private_key(data: bytes) -> bool:
+    """Heuristic: does ``data`` contain recognizable private-key material?
+
+    Detects PEM/OpenSSH/PuTTY private keys and private JWKs (a ``"d"`` member
+    next to ``"kty"``). Publishing tools use this to keep signing keys out of
+    bundles (§2).
+    """
+    if any(marker in data for marker in _PRIVATE_MARKERS):
+        return True
+    return bool(
+        re.search(rb'"kty"\s*:', data) and re.search(rb'"d"\s*:\s*"[A-Za-z0-9_-]{20,}', data)
+    )

pysci/manifest.py

@@ -0,0 +1,302 @@
+"""The signed manifest (protocol §3) and manifest checks (§6.1)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from . import ed25519
+from .errors import Invalid, Issue, IssueCollector
+from .ids import parse_publication_id
+from .jsonstrict import MAX_SAFE_INTEGER, JsonInt, JsonObject, json_pointer, json_type_name
+from .jsonstrict import parse_json_object as _parse_json_object
+from .keys import PublicKey, parse_public_jwk, public_key_of
+from .paths import check_paths, path_sort_key
+from .schemas import PUBLICATION_SCHEMA, check_schema
+
+__all__ = [
+    "MANIFEST_PATH",
+    "REQUIRED_FILES",
+    "SIGNATURE_PATH",
+    "TIMESTAMP_SIDECAR_PATH",
+    "FileEntry",
+    "Manifest",
+    "build_manifest",
+    "parse_manifest",
+    "serialize_manifest",
+    "sign_manifest",
+    "verify_manifest",
+]
+
+MANIFEST_PATH: Final = "manifest.json"
+SIGNATURE_PATH: Final = "manifest.json.sig"
+TIMESTAMP_SIDECAR_PATH: Final = "manifest.json.sig.tsr"
+METADATA_PATH: Final = "sci.json"
+README_PATH: Final = "README.md"
+LICENSE_PATH: Final = "LICENSE"
+REQUIRED_FILES: Final = (METADATA_PATH, README_PATH)
+_ROOT_FILES: Final = frozenset({METADATA_PATH, README_PATH, LICENSE_PATH})
+_SHA256_HEX: Final = re.compile(r"[0-9a-f]{64}")
+_BYTES_LEXEME: Final = re.compile(r"0|[1-9][0-9]*")
+
+
+@dataclass(frozen=True, slots=True)
+class FileEntry:
+    """One manifest ``files`` member."""
+
+    sha256: str
+    bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class Manifest:
+    """A parsed manifest. ``raw`` is the exact signed byte string."""
+
+    raw: bytes
+    public_key: PublicKey
+    files: Mapping[str, FileEntry]
+
+    @property
+    def digest(self) -> str:
+        """Bare SHA-256 hex digest of the manifest bytes."""
+        return hashlib.sha256(self.raw).hexdigest()
+
+    @property
+    def publication_id(self) -> str:
+        """``sha256:<digest>`` identifier (§2)."""
+        return "sha256:" + self.digest
+
+    def sorted_paths(self) -> list[str]:
+        """Listed paths in ZIP order (ascending ASCII bytes)."""
+        return sorted(self.files, key=path_sort_key)
+
+
+def parse_manifest(data: bytes, *, file: str = MANIFEST_PATH) -> Manifest:
+    """Check JSON encoding, fields, types, values, and paths (§3, §3.1, §7).
+
+    The signature is not checked; use :func:`verify_manifest`.
+
+    Raises:
+        Invalid: one or more violations (all independent field issues are reported).
+        Unsupported: the schema string is unknown.
+    """
+    record = _parse_json_object(data, file=file)
+    check_schema(record, PUBLICATION_SCHEMA, file=file)
+    issues = IssueCollector()
+    _check_members(record, ("schema", "public_key", "files"), file, issues)
+    public_key = None
+    if "public_key" in record:
+        public_key = parse_public_jwk(record["public_key"], file=file, collector=issues)
+    files = _parse_files(record.get("files"), "files" in record, file, issues)
+    issues.raise_if_any()
+    assert public_key is not None
+    assert files is not None
+    return Manifest(raw=bytes(data), public_key=public_key, files=files)
+
+
+def _check_members(
+    record: JsonObject, required: tuple[str, ...], file: str, issues: IssueCollector
+) -> None:
+    missing = [name for name in required if name not in record]
+    extra = sorted(set(record) - set(required))
+    if missing:
+        issues.add(
+            "manifest_fields",
+            "manifest requires schema, public_key, and files",
+            section="3",
+            file=file,
+            observed=missing,
+        )
+    if extra:
+        issues.add(
+            "manifest_fields",
+            "manifest permits only schema, public_key, and files",
+            section="3",
+            file=file,
+            observed=extra,
+        )
+
+
+def _parse_files(
+    value: object, present: bool, file: str, issues: IssueCollector
+) -> dict[str, FileEntry] | None:
+    if not present:
+        return None
+    if not isinstance(value, dict):
+        issues.add(
+            "manifest_files_type",
+            "files must be a JSON object",
+            section="3",
+            file=file,
+            field="/files",
+            observed=json_type_name(value),
+        )
+        return None
+    entries: dict[str, FileEntry] = {}
+    start = len(issues)
+    for path, entry in value.items():
+        where = json_pointer("files", path)
+        if not isinstance(entry, dict):
+            issues.add(
+                "manifest_entry_type",
+                "each files member must be an object",
+                section="3",
+                file=file,
+                field=where,
+                observed=json_type_name(entry),
+            )
+            continue
+        if set(entry) != {"sha256", "bytes"}:
+            issues.add(
+                "manifest_entry_fields",
+                "each entry has exactly sha256 and bytes",
+                section="3",
+                file=file,
+                field=where,
+                observed=sorted(entry),
+            )
+        digest = entry.get("sha256")
+        if not (isinstance(digest, str) and _SHA256_HEX.fullmatch(digest)):
+            issues.add(
+                "manifest_sha256",
+                "sha256 must be 64 lowercase hexadecimal characters",
+                section="3",
+                file=file,
+                field=where + "/sha256",
+                observed=digest,
+            )
+        size = entry.get("bytes")
+        if not (
+            type(size) is JsonInt
+            and _BYTES_LEXEME.fullmatch(size.lexeme)
+            and 0 <= size <= MAX_SAFE_INTEGER
+        ):
+            observed = size.lexeme if isinstance(size, JsonInt) else size
+            issues.add(
+                "manifest_bytes",
+                "bytes must be a digits-only integer from 0 through 9007199254740991",
+                section="3",
+                file=file,
+                field=where + "/bytes",
+                observed=getattr(size, "lexeme", observed),
+            )
+        if len(issues) == start:
+            assert isinstance(digest, str)
+            assert isinstance(size, int)
+            entries[path] = FileEntry(sha256=digest, bytes=int(size))
+    for required in REQUIRED_FILES:
+        if required not in value:
+            issues.add(
+                "manifest_required_file",
+                f"files must list {required}",
+                section="3",
+                file=file,
+                field="/files",
+                observed=required,
+            )
+    for path in value:
+        if path not in _ROOT_FILES and not path.startswith("files/"):
+            issues.add(
+                "manifest_path_location",
+                "entries other than sci.json, README.md, and LICENSE must be under files/",
+                section="3",
+                file=file,
+                field=json_pointer("files", path),
+                observed=path,
+            )
+    check_paths(value.keys(), collector=issues, file=file, field_prefix="/files")
+    return entries if len(issues) == start else None
+
+
+def verify_manifest(
+    manifest_bytes: bytes,
+    signature: bytes,
+    *,
+    expected_id: str | None = None,
+    file: str = MANIFEST_PATH,
+) -> Manifest:
+    """Complete the §6.1 manifest checks.
+
+    Checks the JSON encoding, fields, and paths; computes the publication
+    identifier and compares it with ``expected_id`` (any accepted ID spelling);
+    then checks the public key and signature over the original bytes.
+
+    Raises:
+        Invalid, Unsupported: see :func:`parse_manifest`; also a mismatched
+            identifier or signature failure.
+    """
+    manifest = parse_manifest(manifest_bytes, file=file)
+    if expected_id is not None:
+        expected = parse_publication_id(expected_id, allow_bare=True)
+        if manifest.digest != expected:
+            raise Invalid(
+                Issue(
+                    "publication_id_mismatch",
+                    "manifest hash must equal the requested publication identifier",
+                    section="6.1",
+                    file=file,
+                    observed=manifest.publication_id,
+                )
+            )
+    ed25519.verify(manifest.public_key.raw, signature, manifest.raw, file=SIGNATURE_PATH)
+    return manifest
+
+
+def build_manifest(public_key: PublicKey, files: Mapping[str, FileEntry]) -> bytes:
+    """Serialize a manifest with the stable SCI serializer.
+
+    Members appear as ``schema``, ``public_key``, ``files``; file paths are in
+    ascending ASCII byte order; output is compact UTF-8 JSON with no
+    insignificant whitespace. Paths are validated before serialization.
+
+    Raises:
+        Invalid: a path, hash, or size would make the manifest invalid.
+    """
+    issues = IssueCollector()
+    check_paths(files.keys(), collector=issues, field_prefix="/files")
+    for required in REQUIRED_FILES:
+        if required not in files:
+            issues.add("manifest_required_file", f"files must list {required}", section="3")
+    for path, entry in files.items():
+        if path not in _ROOT_FILES and not path.startswith("files/"):
+            issues.add(
+                "manifest_path_location",
+                "entries other than sci.json, README.md, and LICENSE must be under files/",
+                section="3",
+                observed=path,
+            )
+        if not _SHA256_HEX.fullmatch(entry.sha256) or not 0 <= entry.bytes <= MAX_SAFE_INTEGER:
+            issues.add("manifest_entry", "invalid file hash or size", section="3", observed=path)
+    issues.raise_if_any()
+    return serialize_manifest(public_key, files)
+
+
+def serialize_manifest(public_key: PublicKey, files: Mapping[str, FileEntry]) -> bytes:
+    """The stable serializer used by :func:`build_manifest`, without validation.
+
+    Useful for planning sizes of drafts that still have problems.
+    Non-ASCII characters are written as JSON escapes.
+    """
+    document = {
+        "schema": PUBLICATION_SCHEMA,
+        "public_key": public_key.to_jwk(),
+        "files": {
+            path: {"sha256": files[path].sha256, "bytes": files[path].bytes}
+            for path in sorted(files, key=path_sort_key)
+        },
+    }
+    return json.dumps(document, ensure_ascii=True, separators=(",", ":")).encode("ascii")
+
+
+def sign_manifest(manifest_bytes: bytes, private_key: Ed25519PrivateKey) -> bytes:
+    """Sign exact manifest bytes after checking the embedded key matches."""
+    manifest = parse_manifest(manifest_bytes)
+    if manifest.public_key != public_key_of(private_key):
+        raise ValueError("private key does not match the manifest public_key")
+    return ed25519.sign(private_key, manifest_bytes)