sci-protocol 0.2.0__py3-none-any.whl

pysci/png.py

@@ -0,0 +1,217 @@
+"""PNG display files in baseline publications (protocol §2.1) and the §6.2 decode check.
+
+:class:`PngStructure` is the required baseline check. It streams, keeps a few
+bytes of state, and does not verify CRCs or decode. :func:`png_decode_problem`
+is the additional check that §6.2 recommends for publishing tools.
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+from typing import Final
+
+__all__ = [
+    "DISPLAY_MAX_BYTES",
+    "DISPLAY_MAX_DIMENSION",
+    "DISPLAY_MAX_PIXELS",
+    "PngStructure",
+    "display_problem",
+    "is_display_candidate",
+    "png_decode_problem",
+]
+
+DISPLAY_MAX_BYTES: Final = 2 * 1024 * 1024
+DISPLAY_MAX_PIXELS: Final = 8_000_000
+DISPLAY_MAX_DIMENSION: Final = 8192
+
+_SIGNATURE: Final = b"\x89PNG\r\n\x1a\n"
+_ANIMATION: Final = frozenset({b"acTL", b"fcTL", b"fdAT"})
+_CRITICAL: Final = frozenset({b"IHDR", b"PLTE", b"IDAT", b"IEND"})
+_DEPTHS: Final = {0: (1, 2, 4, 8, 16), 2: (8, 16), 3: (1, 2, 4, 8), 4: (8, 16), 6: (8, 16)}
+_CHANNELS: Final = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}
+_ADAM7: Final = (
+    (0, 0, 8, 8),
+    (4, 0, 8, 8),
+    (0, 4, 4, 8),
+    (2, 0, 4, 4),
+    (0, 2, 2, 4),
+    (1, 0, 2, 2),
+    (0, 1, 1, 2),
+)
+_STAGE_SIGNATURE, _STAGE_HEADER, _STAGE_CHUNKS, _STAGE_ENDED = range(4)
+_NEEDED: Final = {_STAGE_SIGNATURE: 8, _STAGE_HEADER: 16, _STAGE_CHUNKS: 8}
+
+
+def _has_png_extension(path: str) -> bool:
+    return path[-4:].lower() == ".png"
+
+
+def is_display_candidate(path: str, size: int) -> bool:
+    """True if the path and size allow a baseline display file."""
+    return _has_png_extension(path) and size <= DISPLAY_MAX_BYTES
+
+
+class PngStructure:
+    """Streaming §2.1 checks: signature, chunk layout, ``IHDR`` dimensions, no animation."""
+
+    __slots__ = ("_failure", "_pending", "_skip", "_stage")
+
+    def __init__(self) -> None:
+        self._stage = _STAGE_SIGNATURE
+        self._pending = bytearray()
+        self._skip = 0
+        self._failure: str | None = None
+
+    def feed(self, data: bytes) -> None:
+        offset = 0
+        while offset < len(data) and self._failure is None:
+            if self._skip:
+                step = min(self._skip, len(data) - offset)
+                self._skip -= step
+                offset += step
+            elif self._stage == _STAGE_ENDED:
+                self._failure = "bytes follow the IEND chunk"
+            else:
+                needed = _NEEDED[self._stage]
+                step = min(needed - len(self._pending), len(data) - offset)
+                self._pending += data[offset : offset + step]
+                offset += step
+                if len(self._pending) == needed:
+                    self._consume(bytes(self._pending))
+                    self._pending.clear()
+
+    def _consume(self, header: bytes) -> None:
+        if self._stage == _STAGE_SIGNATURE:
+            if header != _SIGNATURE:
+                self._failure = "the file does not start with the PNG signature"
+            self._stage = _STAGE_HEADER
+            return
+        size, kind = struct.unpack_from(">I4s", header)
+        if kind in _ANIMATION:
+            self._failure = "animated PNG chunks are not allowed"
+        elif self._stage == _STAGE_HEADER:
+            if kind != b"IHDR" or size != 13:
+                self._failure = "the first chunk must be IHDR with 13 data bytes"
+                return
+            width, height = struct.unpack_from(">II", header, 8)
+            if not (
+                1 <= width <= DISPLAY_MAX_DIMENSION
+                and 1 <= height <= DISPLAY_MAX_DIMENSION
+                and width * height <= DISPLAY_MAX_PIXELS
+            ):
+                self._failure = f"{width} x {height} pixels is outside the display limits"
+                return
+            self._stage = _STAGE_CHUNKS
+            self._skip = size - 8 + 4
+        elif kind == b"IHDR":
+            self._failure = "only one IHDR chunk is allowed"
+        elif kind == b"IEND":
+            if size:
+                self._failure = "the IEND chunk must be empty"
+            self._stage = _STAGE_ENDED
+            self._skip = 4
+        else:
+            self._skip = size + 4
+
+    def problem(self) -> str | None:
+        """Why the bytes fed so far fail the checks, or None if they pass."""
+        if self._failure is not None:
+            return self._failure
+        if self._stage != _STAGE_ENDED or self._skip or self._pending:
+            return "the file ends before a complete IEND chunk"
+        return None
+
+
+def display_problem(path: str, size: int, structure: PngStructure | None) -> str | None:
+    """Why a display file is outside the baseline, or None if it meets §2.1."""
+    if not _has_png_extension(path):
+        return "the extension is not .png"
+    if size > DISPLAY_MAX_BYTES:
+        return f"{size:,} bytes exceeds {DISPLAY_MAX_BYTES:,}"
+    if structure is None:
+        return "the file was not checked"
+    return structure.problem()
+
+
+def _expected_scanlines(width: int, height: int, depth: int, color: int, interlaced: bool) -> int:
+    channels = _CHANNELS[color]
+    total = 0
+    for x, y, dx, dy in _ADAM7 if interlaced else ((0, 0, 1, 1),):
+        columns = (width - x + dx - 1) // dx
+        rows = (height - y + dy - 1) // dy
+        if columns > 0 and rows > 0:
+            total += ((columns * depth * channels + 7) // 8 + 1) * rows
+    return total
+
+
+def png_decode_problem(data: bytes) -> str | None:
+    """Why a PNG that passed :class:`PngStructure` cannot be decoded, or None (§6.2).
+
+    Checks CRCs, ``IHDR`` fields, required chunks, and the exact inflated size.
+    Inflated data is bounded by the §2.1 pixel limit.
+    """
+    offset = 8
+    idat = bytearray()
+    idat_closed = False
+    palette = False
+    width = height = depth = color = interlace = 0
+    while offset < len(data):
+        size, kind = struct.unpack_from(">I4s", data, offset)
+        body = data[offset + 8 : offset + 8 + size]
+        stored = struct.unpack_from(">I", data, offset + 8 + size)[0]
+        if zlib.crc32(kind + body) != stored:
+            return f"chunk {kind.decode('latin-1')} has a bad CRC"
+        if not kind[0] & 0x20 and kind not in _CRITICAL:
+            return f"unknown critical chunk {kind.decode('latin-1')}"
+        if kind == b"IHDR":
+            width, height, depth, color, compression, filtering, interlace = struct.unpack(
+                ">IIBBBBB", body
+            )
+            if depth not in _DEPTHS.get(color, ()):
+                return f"invalid color type {color} with bit depth {depth}"
+            if compression or filtering or interlace > 1:
+                return "unsupported IHDR compression, filter, or interlace method"
+        elif kind == b"PLTE":
+            palette = True
+        elif kind == b"IDAT":
+            if idat_closed:
+                return "IDAT chunks must be consecutive"
+            idat += body
+        elif idat:
+            idat_closed = True
+        offset += 12 + size
+    if color == 3 and not palette:
+        return "palette image without a PLTE chunk"
+    if not idat:
+        return "no IDAT chunk"
+    expected = _expected_scanlines(width, height, depth, color, interlace == 1)
+    inflater = zlib.decompressobj()
+    try:
+        pixels = inflater.decompress(bytes(idat), expected + 1)
+        extra = inflater.decompress(inflater.unconsumed_tail, 1) if len(pixels) == expected else b""
+    except zlib.error:
+        return "image data is not a valid zlib stream"
+    if len(pixels) != expected or extra:
+        return "image data does not match the image dimensions"
+    if not inflater.eof or inflater.unused_data:
+        return "image data continues after the end of the zlib stream"
+    return _filter_problem(pixels, width, height, depth, color, interlace == 1)
+
+
+def _filter_problem(
+    pixels: bytes, width: int, height: int, depth: int, color: int, interlaced: bool
+) -> str | None:
+    channels = _CHANNELS[color]
+    position = 0
+    for x, y, dx, dy in _ADAM7 if interlaced else ((0, 0, 1, 1),):
+        columns = (width - x + dx - 1) // dx
+        rows = (height - y + dy - 1) // dy
+        if columns <= 0 or rows <= 0:
+            continue
+        stride = (columns * depth * channels + 7) // 8 + 1
+        for _ in range(rows):
+            if pixels[position] > 4:
+                return "a scanline uses an unknown filter"
+            position += stride
+    return None

pysci/records.py

@@ -0,0 +1,384 @@
+"""Signed key records: claims (§5.2.1, §6.6) and revocations (§5.3, §6.7)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from . import ed25519
+from .accounts import Account, AccountType, account_problem
+from .errors import Invalid, Issue, IssueCollector, Outcome, SciError
+from .jsonstrict import JsonObject, json_type_name, parse_json_object
+from .keys import PublicKey, parse_public_jwk, public_key_of
+from .rfc3339 import format_rfc3339, parse_rfc3339
+from .schemas import CLAIM_SCHEMA, REVOCATION_SCHEMA, check_schema
+from .text import check_text
+
+__all__ = [
+    "DEFAULT_CLAIM_VALIDITY",
+    "REVOCATION_FILES",
+    "Claim",
+    "RecordVerification",
+    "SignedRecord",
+    "create_claim",
+    "create_revocation",
+    "parse_claim",
+    "parse_revocation",
+    "verify_claim",
+    "verify_revocation",
+]
+
+DEFAULT_CLAIM_VALIDITY = timedelta(days=90)
+REVOCATION_FILES = ("revocation.json", "revocation.json.sig", "revocation.json.sig.tsr")
+MAX_NOTE = 2500
+MAX_NAME = 80
+
+
+@dataclass(frozen=True, slots=True)
+class SignedRecord:
+    """Exact record bytes and the raw 64-byte signature over them."""
+
+    record: bytes
+    signature: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class Claim:
+    """A parsed ``sci-key-claim/0.1`` record (§5.2.1)."""
+
+    public_key: PublicKey
+    account: Account
+    expires: datetime
+    note: str | None = None
+    name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordVerification:
+    """Outcome of :func:`verify_claim` or :func:`verify_revocation`."""
+
+    outcome: Outcome
+    issues: tuple[Issue, ...] = ()
+    public_key: PublicKey | None = None
+    claim: Claim | None = None
+    raw: JsonObject | None = field(default=None, repr=False)
+
+    @property
+    def ok(self) -> bool:
+        return self.outcome is Outcome.VALID
+
+
+def _fields(
+    record: JsonObject,
+    required: tuple[str, ...],
+    optional: tuple[str, ...],
+    file: str,
+    section: str,
+    issues: IssueCollector,
+) -> None:
+    missing = [name for name in required if name not in record]
+    extra = sorted(set(record) - set(required) - set(optional))
+    if missing:
+        issues.add(
+            "record_fields",
+            "record is missing required fields",
+            section=section,
+            file=file,
+            observed=missing,
+        )
+    if extra:
+        issues.add(
+            "record_fields", "record fields are closed", section=section, file=file, observed=extra
+        )
+
+
+def parse_claim(data: bytes, *, file: str = "claim.json") -> Claim:
+    """Check a claim's encoding, schema, and fields (§5.2.1, §7). Signature not checked.
+
+    Raises:
+        Invalid, Unsupported: with all independent field issues attached.
+    """
+    record = parse_json_object(data, file=file)
+    check_schema(record, CLAIM_SCHEMA, file=file)
+    issues = IssueCollector()
+    _fields(
+        record,
+        ("schema", "public_key", "account", "expires"),
+        ("note", "name"),
+        file,
+        "5.2.1",
+        issues,
+    )
+    public_key = None
+    if "public_key" in record:
+        public_key = parse_public_jwk(record["public_key"], file=file, collector=issues)
+    account = None
+    if "account" in record:
+        value = record["account"]
+        if (
+            not isinstance(value, dict)
+            or set(value) != {"type", "id"}
+            or not all(isinstance(v, str) for v in value.values())
+        ):
+            issues.add(
+                "claim_account",
+                "account must have exactly two string fields, type and id",
+                section="5.2.1",
+                file=file,
+                field="/account",
+                observed=json_type_name(value) if not isinstance(value, dict) else sorted(value),
+            )
+        else:
+            account_type, account_id = str(value["type"]), str(value["id"])
+            problem = account_problem(account_type, account_id)
+            if problem is not None and account_type not in set(AccountType):
+                issues.add(
+                    "unsupported_account_type",
+                    "account type has no supported method",
+                    section="5.2",
+                    file=file,
+                    field="/account/type",
+                    observed=account_type,
+                    outcome=Outcome.UNSUPPORTED,
+                )
+            elif problem is not None:
+                issues.add(
+                    "claim_account_id",
+                    problem,
+                    section="5.2",
+                    file=file,
+                    field="/account/id",
+                    observed=account_id,
+                )
+            else:
+                account = Account(account_type, account_id)
+    expires = None
+    if "expires" in record:
+        value = record["expires"]
+        try:
+            if not isinstance(value, str):
+                raise ValueError
+            expires = parse_rfc3339(value)
+        except ValueError:
+            issues.add(
+                "claim_expires",
+                "expires must be an RFC 3339 date-time",
+                section="5.2.1",
+                file=file,
+                field="/expires",
+                observed=value,
+            )
+    note = None
+    if "note" in record:
+        value = record["note"]
+        if not isinstance(value, str):
+            issues.add(
+                "claim_note",
+                "note must be a string",
+                section="5.2.1",
+                file=file,
+                field="/note",
+                observed=json_type_name(value),
+            )
+        else:
+            before = len(issues)
+            check_text(
+                value,
+                multiline=True,
+                nonblank=True,
+                max_code_points=MAX_NOTE,
+                file=file,
+                field="/note",
+                collector=issues,
+            )
+            note = value if len(issues) == before else None
+    name = None
+    if "name" in record:
+        value = record["name"]
+        if not isinstance(value, str):
+            issues.add(
+                "claim_name", "name must be a string", section="5.2.1", file=file, field="/name"
+            )
+        else:
+            check_text(
+                value,
+                nonblank=True,
+                max_code_points=MAX_NAME,
+                file=file,
+                field="/name",
+                collector=issues,
+            )
+            name = value
+    issues.raise_if_any()
+    assert public_key is not None
+    assert account is not None
+    assert expires is not None
+    return Claim(public_key, account, expires, note, name)
+
+
+def verify_claim(
+    record: bytes,
+    signature: bytes,
+    *,
+    expected_public_key: PublicKey | str,
+    requested_account: Account,
+    now: datetime | None = None,
+    retrieved_from_account_location: bool = True,
+    known_revocation: bool = False,
+    file: str = "claim.json",
+) -> RecordVerification:
+    """Key association checks (§6.6) on retrieved claim bytes.
+
+    ``retrieved_from_account_location`` states that the bytes were retrieved
+    from the account method's hosting location (§5.2.2-5.2.4); a local
+    signature alone does not establish a hosted association.
+    ``known_revocation`` is True if a verified revocation for the key is known.
+    """
+    try:
+        claim = parse_claim(record, file=file)
+        ed25519.verify(claim.public_key.raw, signature, record, file=file + ".sig")
+        expected = (
+            expected_public_key
+            if isinstance(expected_public_key, PublicKey)
+            else PublicKey.from_x(expected_public_key)
+        )
+        issues = IssueCollector()
+        if claim.public_key.raw != expected.raw:
+            issues.add(
+                "claim_key_mismatch",
+                "claim public key must equal the expected key",
+                section="6.6",
+                file=file,
+                field="/public_key",
+                observed=claim.public_key.x,
+            )
+        if claim.account != requested_account:
+            issues.add(
+                "claim_account_mismatch",
+                "account type and id must equal the requested account",
+                section="6.6",
+                file=file,
+                field="/account",
+                observed=claim.account.to_json(),
+            )
+        current = now or datetime.now(UTC)
+        if not current < claim.expires:
+            issues.add(
+                "claim_expired",
+                "the current time must be before expires",
+                section="6.6",
+                file=file,
+                field="/expires",
+                observed=format_rfc3339(claim.expires),
+            )
+        if known_revocation:
+            issues.add(
+                "key_revoked",
+                "the key must have no known verified revocation",
+                section="6.6",
+                file=file,
+            )
+        if not retrieved_from_account_location:
+            issues.add(
+                "claim_not_hosted",
+                "the claim must be retrieved from the account's hosting location",
+                section="6.6",
+                file=file,
+            )
+        issues.raise_if_any()
+    except SciError as exc:
+        return RecordVerification(exc.outcome, exc.issues)
+    return RecordVerification(Outcome.VALID, (), claim.public_key, claim)
+
+
+def create_claim(
+    private_key: Ed25519PrivateKey,
+    account: Account,
+    *,
+    expires: datetime | None = None,
+    note: str | None = None,
+    name: str | None = None,
+    now: datetime | None = None,
+) -> SignedRecord:
+    """Create and sign a claim (default expiry 90 days from ``now``).
+
+    The record is serialized compactly with members ``schema``,
+    ``public_key``, ``account``, ``expires``, [``name``], [``note``]; it is re-parsed to
+    guarantee validity.
+    """
+    problem = account_problem(account.type, account.id)
+    if problem is not None:
+        raise ValueError(problem)
+    expiry = expires or (now or datetime.now(UTC)) + DEFAULT_CLAIM_VALIDITY
+    document: dict[str, object] = {
+        "schema": CLAIM_SCHEMA,
+        "public_key": public_key_of(private_key).to_jwk(),
+        "account": account.to_json(),
+        "expires": format_rfc3339(expiry),
+    }
+    if name is not None:
+        document["name"] = name
+    if note is not None:
+        document["note"] = note
+    raw = json.dumps(document, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    parse_claim(raw)
+    return SignedRecord(raw, ed25519.sign(private_key, raw))
+
+
+def parse_revocation(data: bytes, *, file: str = "revocation.json") -> PublicKey:
+    """Check a revocation's encoding, schema, and fields (§5.3); return its key."""
+    record = parse_json_object(data, file=file)
+    check_schema(record, REVOCATION_SCHEMA, file=file)
+    issues = IssueCollector()
+    _fields(record, ("schema", "public_key"), (), file, "5.3", issues)
+    key = None
+    if "public_key" in record:
+        key = parse_public_jwk(record["public_key"], file=file, collector=issues)
+    issues.raise_if_any()
+    assert key is not None
+    return key
+
+
+def verify_revocation(
+    record: bytes,
+    signature: bytes,
+    *,
+    expected_public_key: PublicKey | str | None = None,
+    file: str = "revocation.json",
+) -> RecordVerification:
+    """Revocation checks (§6.7); optionally require the revoked key (§8.1.2)."""
+    try:
+        key = parse_revocation(record, file=file)
+        ed25519.verify(key.raw, signature, record, file=file + ".sig")
+        if expected_public_key is not None:
+            expected = (
+                expected_public_key
+                if isinstance(expected_public_key, PublicKey)
+                else PublicKey.from_x(expected_public_key)
+            )
+            if expected.raw != key.raw:
+                raise Invalid(
+                    Issue(
+                        "revocation_key_mismatch",
+                        "record public_key.x must equal the requested key",
+                        section="8.1.2",
+                        file=file,
+                        field="/public_key/x",
+                        observed=key.x,
+                    )
+                )
+    except SciError as exc:
+        return RecordVerification(exc.outcome, exc.issues)
+    return RecordVerification(Outcome.VALID, (), key)
+
+
+def create_revocation(private_key: Ed25519PrivateKey) -> SignedRecord:
+    """Create and sign a revocation record for ``private_key``'s public key (§5.3)."""
+    raw = json.dumps(
+        {"schema": REVOCATION_SCHEMA, "public_key": public_key_of(private_key).to_jwk()},
+        separators=(",", ":"),
+    ).encode("ascii")
+    return SignedRecord(raw, ed25519.sign(private_key, raw))

pysci/rfc3339.py

@@ -0,0 +1,66 @@
+"""RFC 3339 §5.6 ``date-time`` parsing and formatting."""
+
+from __future__ import annotations
+
+import calendar
+import re
+from datetime import UTC, datetime, timedelta, timezone
+from typing import Final
+
+__all__ = ["format_rfc3339", "parse_rfc3339"]
+
+_DATE_TIME: Final = re.compile(
+    r"(?P<year>[0-9]{4})-(?P<month>[0-9]{2})-(?P<day>[0-9]{2})[Tt]"
+    r"(?P<hour>[0-9]{2}):(?P<minute>[0-9]{2}):(?P<second>[0-9]{2})(?P<fraction>\.[0-9]+)?"
+    r"(?P<offset>[Zz]|[+-][0-9]{2}:[0-9]{2})"
+)
+
+
+def parse_rfc3339(value: str) -> datetime:
+    """Parse an RFC 3339 ``date-time`` into an aware datetime.
+
+    Field ranges are checked (including days per month). A leap second
+    (``:60``) is accepted only at 23:59 UTC-equivalent minute boundaries and
+    is represented as the following second.
+
+    Raises:
+        ValueError: not an RFC 3339 date-time.
+    """
+    match = _DATE_TIME.fullmatch(value)
+    if match is None:
+        raise ValueError("not an RFC 3339 date-time")
+    year, month, day = int(match["year"]), int(match["month"]), int(match["day"])
+    hour, minute, second = int(match["hour"]), int(match["minute"]), int(match["second"])
+    if not 1 <= month <= 12 or not 1 <= day <= calendar.monthrange(year, month)[1]:
+        raise ValueError("date out of range")
+    if hour > 23 or minute > 59 or second > 60:
+        raise ValueError("time out of range")
+    offset_text = match["offset"]
+    if offset_text in ("Z", "z"):
+        tz: timezone = UTC
+    else:
+        hours, minutes = int(offset_text[1:3]), int(offset_text[4:6])
+        if hours > 23 or minutes > 59:
+            raise ValueError("offset out of range")
+        delta = timedelta(hours=hours, minutes=minutes)
+        tz = timezone(-delta if offset_text[0] == "-" else delta)
+    microsecond = 0
+    if match["fraction"]:
+        microsecond = int((match["fraction"][1:] + "000000")[:6])
+    leap = second == 60
+    result = datetime(
+        year, month, day, hour, minute, 59 if leap else second, microsecond, tzinfo=tz
+    )
+    if leap:
+        utc = result.astimezone(UTC)
+        if (utc.hour, utc.minute) != (23, 59):
+            raise ValueError("leap seconds occur only at the end of a UTC day")
+        result += timedelta(seconds=1)
+    return result
+
+
+def format_rfc3339(value: datetime) -> str:
+    """Format an aware datetime as ``YYYY-MM-DDTHH:MM:SSZ`` in UTC (fractions dropped)."""
+    if value.tzinfo is None:
+        raise ValueError("datetime must be timezone-aware")
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")