sci-protocol 0.2.0__py3-none-any.whl

pysci/schemas.py

@@ -0,0 +1,75 @@
+"""Record schema identifiers and the schema check of §5.1/§6."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .errors import Invalid, Issue, Outcome, Unsupported
+from .jsonstrict import JsonObject, json_type_name
+
+__all__ = [
+    "ARCHIVE_SCHEMA",
+    "CLAIM_SCHEMA",
+    "INDEX_SCHEMA",
+    "KNOWN_SCHEMAS",
+    "PROTOCOL_VERSION",
+    "PUBLICATION_SCHEMA",
+    "REVOCATION_SCHEMA",
+    "check_schema",
+]
+
+PROTOCOL_VERSION: Final = "0.1"
+PUBLICATION_SCHEMA: Final = "sci-publication/0.1"
+CLAIM_SCHEMA: Final = "sci-key-claim/0.1"
+REVOCATION_SCHEMA: Final = "sci-key-revocation/0.1"
+INDEX_SCHEMA: Final = "sci-index/0.1"
+ARCHIVE_SCHEMA: Final = "sci-archive/0.1"
+KNOWN_SCHEMAS: Final = frozenset(
+    {PUBLICATION_SCHEMA, CLAIM_SCHEMA, REVOCATION_SCHEMA, INDEX_SCHEMA, ARCHIVE_SCHEMA}
+)
+
+
+def check_schema(record: JsonObject, expected: str, *, file: str | None = None) -> None:
+    """Check that ``schema`` names the expected record type and version.
+
+    Raises:
+        Unsupported: the schema string identifies no supported schema.
+        Invalid: the schema is missing, not a string, or a known schema of a
+            different record type.
+    """
+    schema = record.get("schema")
+    if not isinstance(schema, str):
+        raise Invalid(
+            Issue(
+                "schema_missing",
+                "record requires a string schema field",
+                section="5.1",
+                file=file,
+                field="/schema",
+                observed=None if "schema" not in record else json_type_name(schema),
+            )
+        )
+    if schema == expected:
+        return
+    if schema in KNOWN_SCHEMAS:
+        raise Invalid(
+            Issue(
+                "schema_wrong_type",
+                f"schema must identify this record type ({expected})",
+                section="5.1",
+                file=file,
+                field="/schema",
+                observed=schema,
+            )
+        )
+    raise Unsupported(
+        Issue(
+            "schema_unsupported",
+            f"unsupported schema; this library supports {expected}",
+            section="6",
+            file=file,
+            field="/schema",
+            observed=schema,
+            outcome=Outcome.UNSUPPORTED,
+        )
+    )

pysci/source.py

@@ -0,0 +1,166 @@
+"""Random-access byte sources used by the verifiers.
+
+Verification reads bounded ranges and streams large regions in chunks, so a
+64 MiB bundle is never held in memory more than one chunk at a time.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from collections.abc import Iterator
+from pathlib import Path
+from typing import BinaryIO, Final, Protocol, runtime_checkable
+
+__all__ = [
+    "CHUNK_SIZE",
+    "ByteSource",
+    "FileSource",
+    "MemorySource",
+    "PathSource",
+    "SliceSource",
+    "as_source",
+    "iter_chunks",
+]
+
+CHUNK_SIZE: Final = 1 << 20
+
+
+@runtime_checkable
+class ByteSource(Protocol):
+    """Read-only random access to a finite byte string."""
+
+    @property
+    def size(self) -> int: ...
+
+    def read_at(self, offset: int, length: int) -> bytes:
+        """Return exactly ``length`` bytes at ``offset``; raise on short reads."""
+        ...
+
+
+class MemorySource:
+    """A :class:`ByteSource` over bytes already in memory."""
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: bytes | bytearray | memoryview) -> None:
+        self._data = memoryview(data).cast("B") if not isinstance(data, bytes) else data
+
+    @property
+    def size(self) -> int:
+        return len(self._data)
+
+    def read_at(self, offset: int, length: int) -> bytes:
+        _check_range(offset, length, len(self._data))
+        return bytes(self._data[offset : offset + length])
+
+
+class FileSource:
+    """A :class:`ByteSource` over a regular file, opened once.
+
+    The size is captured at open time; reads beyond it fail. Use as a context
+    manager or call :meth:`close`.
+    """
+
+    def __init__(self, path: str | os.PathLike[str]) -> None:
+        self.path = Path(path)
+        self._file: BinaryIO = open(self.path, "rb")  # noqa: SIM115 - closed by close()
+        self._size = os.fstat(self._file.fileno()).st_size
+        self._lock = threading.Lock()
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def read_at(self, offset: int, length: int) -> bytes:
+        _check_range(offset, length, self._size)
+        if hasattr(os, "pread"):
+            data = os.pread(self._file.fileno(), length, offset)
+        else:  # pragma: no cover - Windows
+            with self._lock:
+                self._file.seek(offset)
+                data = self._file.read(length)
+        if len(data) != length:
+            raise OSError(f"short read from {self.path}: file changed during verification")
+        return data
+
+    def close(self) -> None:
+        self._file.close()
+
+    def __enter__(self) -> FileSource:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class PathSource:
+    """A :class:`ByteSource` that opens a file for each read.
+
+    Suitable for loose bundles with many files (no descriptor is held open).
+    The size is captured at construction; a changed file causes ``OSError``.
+    """
+
+    __slots__ = ("_size", "path")
+
+    def __init__(self, path: str | os.PathLike[str], size: int | None = None) -> None:
+        self.path = Path(path)
+        self._size = self.path.stat().st_size if size is None else size
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def read_at(self, offset: int, length: int) -> bytes:
+        _check_range(offset, length, self._size)
+        with open(self.path, "rb") as handle:
+            if os.fstat(handle.fileno()).st_size != self._size:
+                raise OSError(f"{self.path} changed during verification")
+            handle.seek(offset)
+            data = handle.read(length)
+        if len(data) != length:
+            raise OSError(f"short read from {self.path}")
+        return data
+
+
+class SliceSource:
+    """A window of another source."""
+
+    __slots__ = ("_base", "_length", "_offset")
+
+    def __init__(self, base: ByteSource, offset: int, length: int) -> None:
+        _check_range(offset, length, base.size)
+        self._base, self._offset, self._length = base, offset, length
+
+    @property
+    def size(self) -> int:
+        return self._length
+
+    def read_at(self, offset: int, length: int) -> bytes:
+        _check_range(offset, length, self._length)
+        return self._base.read_at(self._offset + offset, length)
+
+
+def _check_range(offset: int, length: int, size: int) -> None:
+    if offset < 0 or length < 0 or offset > size or length > size - offset:
+        raise ValueError(f"read of {length} bytes at {offset} exceeds source size {size}")
+
+
+def iter_chunks(
+    source: ByteSource, offset: int = 0, length: int | None = None, chunk_size: int = CHUNK_SIZE
+) -> Iterator[bytes]:
+    """Yield the range ``[offset, offset + length)`` in bounded chunks."""
+    end = source.size if length is None else offset + length
+    _check_range(offset, end - offset, source.size)
+    position = offset
+    while position < end:
+        step = min(chunk_size, end - position)
+        yield source.read_at(position, step)
+        position += step
+
+
+def as_source(value: ByteSource | bytes | bytearray | memoryview) -> ByteSource:
+    """Wrap bytes-like values; pass sources through."""
+    if isinstance(value, bytes | bytearray | memoryview):
+        return MemorySource(value)
+    return value

pysci/specification.py

@@ -0,0 +1,58 @@
+"""The SCI protocol specification text this library implements (bundled package data)."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from functools import cache
+from importlib import resources
+
+#: SHA-256 of ``protocol/README.md`` for protocol draft 0.1, as pinned by the
+#: conformance corpus (``protocol/test-vectors/0.1/catalog.json``).
+PROTOCOL_SPEC_SHA256 = "311e40720392570938fee3ff67d53e6cef933916b228653d1279a9c3f52afc0d"
+
+_HEADING = re.compile(r"^(#{2,6}) (\d+(?:\.\d+)*)\.? ")
+_ANY_HEADING = re.compile(r"^(#{1,6}) ")
+
+
+@cache
+def protocol_specification() -> str:
+    """Return the complete protocol specification as Markdown.
+
+    Raises:
+        RuntimeError: the packaged file is damaged (hash mismatch).
+    """
+    data = resources.files("pysci").joinpath("data/sci-protocol.md").read_bytes()
+    if hashlib.sha256(data).hexdigest() != PROTOCOL_SPEC_SHA256:
+        raise RuntimeError("bundled protocol specification does not match its pinned hash")
+    return data.decode("utf-8")
+
+
+def specification_section(number: str) -> str | None:
+    """Return one numbered section (e.g. ``"4.4"``) with its subsections, or None."""
+    lines = protocol_specification().splitlines(keepends=True)
+    start: int | None = None
+    level = 0
+    for index, line in enumerate(lines):
+        heading = _ANY_HEADING.match(line)
+        if heading is None:
+            continue
+        if start is None:
+            match = _HEADING.match(line)
+            if match is not None and match.group(2) == number:
+                start, level = index, len(match.group(1))
+        elif len(heading.group(1)) <= level:
+            return "".join(lines[start:index]).rstrip() + "\n"
+    if start is None:
+        return None
+    return "".join(lines[start:]).rstrip() + "\n"
+
+
+def specification_sections() -> list[tuple[str, str]]:
+    """List ``(number, title)`` for every numbered heading, in document order."""
+    sections = []
+    for line in protocol_specification().splitlines():
+        match = _HEADING.match(line)
+        if match:
+            sections.append((match.group(2), line[match.end() :].strip()))
+    return sections

pysci/submission.py

@@ -0,0 +1,225 @@
+"""Publication submission contract (protocol §8.1.4)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .accounts import Account
+from .discovery import is_absolute_url
+from .errors import Invalid, Issue, IssueCollector
+from .ids import is_digest, parse_publication_id
+from .jsonstrict import JsonObject, json_type_name, parse_json_object
+
+__all__ = [
+    "SubmissionError",
+    "SubmissionRequest",
+    "SubmissionResponse",
+    "build_submission_request",
+    "parse_submission_request",
+    "parse_submission_response",
+]
+
+_FILE = "submission"
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionRequest:
+    id: str
+    descriptors: tuple[str, ...]
+    account: Account | None = None
+
+    def to_json_bytes(self) -> bytes:
+        document: dict[str, object] = {"id": self.id, "descriptors": list(self.descriptors)}
+        if self.account is not None:
+            document["account"] = self.account.to_json()
+        return json.dumps(document, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionError:
+    """The §8.1.4 error object."""
+
+    code: str
+    message: str
+    retryable: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionResponse:
+    """A conforming response: success (``id`` set) or error (``error`` set).
+
+    ``body`` keeps the full decoded object so service-specific fields can be
+    reported; protocol success confirms location registration only, not
+    catalog admission.
+    """
+
+    status: int
+    id: str | None
+    error: SubmissionError | None
+    body: JsonObject
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+
+def build_submission_request(
+    publication_id: str, descriptors: Sequence[str], account: Account | None = None
+) -> SubmissionRequest:
+    """Build a request from any accepted ID spelling. Validates the result."""
+    request = SubmissionRequest(
+        parse_publication_id(publication_id, allow_bare=True), tuple(descriptors), account
+    )
+    parse_submission_request(request.to_json_bytes())
+    return request
+
+
+def parse_submission_request(data: bytes) -> SubmissionRequest:
+    """Validate a request body (§8.1.4). Raises :class:`~pysci.errors.Invalid` with all issues."""
+    record = parse_json_object(data, file=_FILE)
+    issues = IssueCollector()
+    missing = [name for name in ("id", "descriptors") if name not in record]
+    extra = sorted(set(record) - {"id", "descriptors", "account"})
+    if missing:
+        issues.add(
+            "submission_fields",
+            "request requires id and descriptors",
+            section="8.1.4",
+            file=_FILE,
+            observed=missing,
+        )
+    if extra:
+        issues.add(
+            "submission_fields",
+            "request permits only id, descriptors, and account",
+            section="8.1.4",
+            file=_FILE,
+            observed=extra,
+        )
+    publication = record.get("id")
+    if "id" in record and not (isinstance(publication, str) and is_digest(publication)):
+        issues.add(
+            "submission_id",
+            "id must be 64 lowercase hexadecimal characters without a prefix",
+            section="8.1.1",
+            file=_FILE,
+            field="/id",
+            observed=publication,
+        )
+    descriptors = record.get("descriptors")
+    if "descriptors" in record:
+        if not isinstance(descriptors, list) or not descriptors:
+            issues.add(
+                "submission_descriptors",
+                "descriptors must be a nonempty array",
+                section="8.1.4",
+                file=_FILE,
+                field="/descriptors",
+                observed=json_type_name(descriptors),
+            )
+        else:
+            for index, url in enumerate(descriptors):
+                if not (isinstance(url, str) and is_absolute_url(url)):
+                    issues.add(
+                        "submission_descriptors",
+                        "each descriptor must be an absolute URL string",
+                        section="8.1.4",
+                        file=_FILE,
+                        field=f"/descriptors/{index}",
+                        observed=url,
+                    )
+            if len({json.dumps(u) for u in descriptors}) != len(descriptors):
+                issues.add(
+                    "submission_descriptors",
+                    "descriptors must be distinct",
+                    section="8.1.4",
+                    file=_FILE,
+                    field="/descriptors",
+                )
+    account = None
+    if "account" in record:
+        value = record["account"]
+        if not (
+            isinstance(value, dict)
+            and set(value) == {"type", "id"}
+            and all(isinstance(v, str) for v in value.values())
+        ):
+            issues.add(
+                "submission_account",
+                "account must have exactly two string fields, type and id",
+                section="5.2.1",
+                file=_FILE,
+                field="/account",
+                observed=sorted(value) if isinstance(value, dict) else json_type_name(value),
+            )
+        else:
+            account = Account(str(value["type"]), str(value["id"]))
+    issues.raise_if_any()
+    assert isinstance(publication, str)
+    assert isinstance(descriptors, list)
+    return SubmissionRequest(publication, tuple(str(u) for u in descriptors), account)
+
+
+def parse_submission_response(
+    status: int, content_type: str | None, body: bytes, requested_id: str
+) -> SubmissionResponse:
+    """Validate a response against the §8.1.4 contract.
+
+    Success is ``200``/``201`` with an object whose ``id`` equals the
+    requested digest; errors are ``4xx``/``5xx`` with an ``error`` object
+    holding string ``code``, string ``message``, and Boolean ``retryable``.
+    Both require ``application/json``.
+
+    Raises:
+        Invalid: the response violates the contract (e.g. wrong status class,
+            content type, ID, or error shape).
+    """
+
+    def fail(code: str, requirement: str, observed: object = None) -> Invalid:
+        return Invalid(
+            Issue(
+                code,
+                requirement,
+                section="8.1.4",
+                file=_FILE,
+                observed=None if observed is None else str(observed),
+            )
+        )
+
+    requested = parse_publication_id(requested_id, allow_bare=True)
+    media_type = (content_type or "").split(";", 1)[0].strip().lower()
+    if media_type != "application/json":
+        raise fail("submission_content_type", "responses must use application/json", content_type)
+    record = parse_json_object(body, file=_FILE)
+    if status in (200, 201):
+        if record.get("id") != requested:
+            raise fail(
+                "submission_response_id",
+                "success response id must equal the requested digest",
+                record.get("id"),
+            )
+        return SubmissionResponse(status, requested, None, record)
+    if 400 <= status <= 599:
+        error = record.get("error")
+        if not (
+            isinstance(error, dict)
+            and isinstance(error.get("code"), str)
+            and isinstance(error.get("message"), str)
+            and type(error.get("retryable")) is bool
+        ):
+            raise fail(
+                "submission_error_shape",
+                "error responses need an error object with "
+                "string code, string message, and Boolean retryable",
+            )
+        return SubmissionResponse(
+            status,
+            None,
+            SubmissionError(str(error["code"]), str(error["message"]), bool(error["retryable"])),
+            record,
+        )
+    raise fail(
+        "submission_status", "responses use 200/201 for success or 4xx/5xx for errors", status
+    )

pysci/templates.py

@@ -0,0 +1,129 @@
+"""RFC 6570 URI templates restricted to the expressions used by SCI (§8).
+
+Only single-variable Level 1 (``{var}``) and Level 2 reserved (``{+var}``)
+expressions are supported, which covers every expression the protocol
+permits: ``{id}``, ``{id2}``, ``{x}``, ``{file}``, ``{sha256}``, ``{+path}``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = ["Expression", "UrlTemplate", "parse_template"]
+
+_UNRESERVED: Final = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")
+_RESERVED: Final = frozenset(":/?#[]@!$&'()*+,;=")
+_VARNAME: Final = re.compile(
+    r"(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})+(?:\.(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})+)*"
+)
+_FORBIDDEN_LITERAL: Final = frozenset(" \"'<>\\^`{|}")
+_HEX: Final = frozenset("0123456789abcdefABCDEF")
+
+
+@dataclass(frozen=True, slots=True)
+class Expression:
+    """One template expression; ``operator`` is ``""`` or ``"+"``."""
+
+    operator: str
+    name: str
+
+    def __str__(self) -> str:
+        return "{" + self.operator + self.name + "}"
+
+
+@dataclass(frozen=True, slots=True)
+class UrlTemplate:
+    """A parsed template: literal strings interleaved with expressions."""
+
+    text: str
+    parts: tuple[str | Expression, ...]
+
+    @property
+    def expressions(self) -> frozenset[Expression]:
+        return frozenset(p for p in self.parts if isinstance(p, Expression))
+
+    def expand(self, variables: Mapping[str, str]) -> str:
+        """Expand with string values (RFC 6570 §3.2.2 simple, §3.2.3 reserved).
+
+        Raises:
+            KeyError: a variable is missing.
+        """
+        out: list[str] = []
+        for part in self.parts:
+            if isinstance(part, str):
+                out.append(_encode(part, allow_reserved=True))
+            else:
+                out.append(_encode(variables[part.name], allow_reserved=part.operator == "+"))
+        return "".join(out)
+
+
+def _encode(value: str, *, allow_reserved: bool) -> str:
+    allowed = _UNRESERVED | _RESERVED if allow_reserved else _UNRESERVED
+    out: list[str] = []
+    index = 0
+    while index < len(value):
+        ch = value[index]
+        if (
+            allow_reserved
+            and ch == "%"
+            and index + 2 < len(value)
+            and value[index + 1] in _HEX
+            and value[index + 2] in _HEX
+        ):
+            out.append(value[index : index + 3])
+            index += 3
+            continue
+        if ch in allowed:
+            out.append(ch)
+        else:
+            out.extend(f"%{byte:02X}" for byte in ch.encode("utf-8"))
+        index += 1
+    return "".join(out)
+
+
+def parse_template(text: str) -> UrlTemplate:
+    """Parse a template restricted to ``{var}`` and ``{+var}`` expressions.
+
+    Raises:
+        ValueError: malformed template, unsupported operator or modifier, or a
+            literal character RFC 6570 does not permit.
+    """
+    parts: list[str | Expression] = []
+    literal: list[str] = []
+    index = 0
+    while index < len(text):
+        ch = text[index]
+        if ch == "{":
+            end = text.find("}", index + 1)
+            if end < 0:
+                raise ValueError("unclosed template expression")
+            body = text[index + 1 : end]
+            if "{" in body:
+                raise ValueError("nested '{' in template expression")
+            operator = ""
+            if body[:1] == "+":
+                operator, body = "+", body[1:]
+            elif body[:1] and not (body[0].isalnum() or body[0] in "_%"):
+                raise ValueError(f"unsupported template operator {body[0]!r}")
+            if not _VARNAME.fullmatch(body):
+                raise ValueError(f"unsupported template expression {text[index : end + 1]!r}")
+            if literal:
+                parts.append("".join(literal))
+                literal = []
+            parts.append(Expression(operator, body))
+            index = end + 1
+            continue
+        if ch == "}" or ch in _FORBIDDEN_LITERAL or ord(ch) < 0x21 or ord(ch) == 0x7F:
+            raise ValueError(f"character {ch!r} is not permitted in a URI template literal")
+        if ch == "%" and not (
+            index + 2 < len(text) and text[index + 1] in _HEX and text[index + 2] in _HEX
+        ):
+            raise ValueError("'%' must begin a percent-encoded triplet")
+        literal.append(ch)
+        index += 1
+    if literal:
+        parts.append("".join(literal))
+    return UrlTemplate(text, tuple(parts))