moca-reader 0.6.0__py3-none-any.whl

moca_reader/content.py

@@ -0,0 +1,312 @@
+"""Content traversal: content/ is an Open Knowledge Format (OKF) v0.2 bundle (package spec §5, contract §5)."""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._js import decode_uri_component, get, js_sorted, js_trim, posix_dirname, posix_join, truthy, utf16_key
+from .diagnostics import Diagnostics
+from .evidence_text import check_selector, normalised_text, source_kind
+from .frontmatter import split_frontmatter
+from .schemas import validate_against
+from .unicode import normalize
+
+CONTENT_DIR = "content"
+_RESERVED = {"index.md", "log.md"}
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+_LINK = re.compile(
+    r"!?\[[^\]]*\]\([\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(<[^>]+>|[^)\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+)(?:[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+(?:\"[^\"]*\"|'[^']*'))?[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*\)"
+)
+_PATH_REF = re.compile(r"^(\.{1,2}/|/)")
+_EVIDENCE_DIRS = ("sources/", "media/")
+_LOCALE = re.compile(r"^(.*)\.([A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*)\.md\Z", re.IGNORECASE | re.ASCII | re.DOTALL)
+
+
+@dataclass
+class EvidenceCheck:
+    local: bool
+    matched: bool | None = None
+
+
+@dataclass
+class Representation:
+    locale: str | None  # None = the default language
+    file: str  # package-relative path
+    frontmatter: dict[str, Any]
+    body: str
+    body_offset: int  # UTF-8 byte offset of the body in the file
+    sha256: str | None
+    evidence_checks: list[EvidenceCheck] = field(default_factory=list)
+    concepts: list[str] | None = None
+
+
+@dataclass
+class ContentNode:
+    path: str  # relative to content/: the default-language file name
+    representations: list[Representation]
+
+
+def read_content(
+    manifest: dict[str, Any],
+    files: dict[str, str],
+    data: dict[str, bytes],
+    file_digests: dict[str, str],
+    diagnostics: Diagnostics,
+    limits: dict[str, int],
+) -> list[ContentNode]:
+    source_text: dict[str, str] = {}
+    # Contract §3: a per-package budget of evidence checks and of source bytes scanned.
+    budget: dict[str, Any] = {"checks": 0, "bytes": 0, "prepared": {}}
+    declared = manifest.get("locales")
+    locales = {str(loc).lower(): loc for loc in (declared if isinstance(declared, list) else [])}
+    by_key: dict[str, ContentNode] = {}
+    md_files = js_sorted(p for p in files if p.startswith(f"{CONTENT_DIR}/") and p.lower().endswith(".md"))
+
+    for file in md_files:
+        rel = file[len(CONTENT_DIR) + 1 :]
+        base = posixpath.basename(rel)
+        text = data[file].decode("utf-8", errors="replace")
+
+        if base.lower() in _RESERVED:
+            _check_reserved(file, rel, base.lower(), text, diagnostics, limits)
+            continue
+
+        key, locale = _locale_of(rel, locales)
+        split = split_frontmatter(text, limits["maxFrontmatterBytes"])
+        if not split.present:
+            diagnostics.add(
+                "C001_FRONTMATTER_MISSING", "concept documents must open with a YAML frontmatter block", file
+            )
+            continue
+        if split.error:
+            diagnostics.add("C002_FRONTMATTER_INVALID", split.error, file, split.line)
+            continue
+        fm: dict[str, Any] = split.data
+        if not isinstance(fm.get("type"), str) or js_trim(fm["type"]) == "":
+            diagnostics.add("C003_TYPE_MISSING", 'frontmatter needs a non-empty "type"', file)
+            continue
+        for err in validate_against("node", fm):
+            diagnostics.add("C005_FIELD_INVALID", err, file)
+        _check_evidence(file, fm, diagnostics)
+        _check_window(file, fm, diagnostics)
+        _check_paths(file, fm, split.body, files, diagnostics)
+        checks = _verify_evidence(file, fm, files, data, diagnostics, limits, source_text, budget)
+
+        rep = Representation(locale, file, fm, split.body, split.body_offset, file_digests.get(file), checks)
+        by_key.setdefault(key, ContentNode(key, [])).representations.append(rep)
+
+    nodes: list[ContentNode] = []
+    for node in sorted(by_key.values(), key=lambda n: utf16_key(n.path)):
+        node.representations.sort(key=lambda r: (r.locale is not None, utf16_key(r.locale or "")))
+        if node.representations[0].locale is not None:
+            diagnostics.add(
+                "C009_LOCALE_ORPHAN",
+                f"locale variant has no default-language file {CONTENT_DIR}/{node.path}",
+                node.representations[0].file,
+            )
+        nodes.append(node)
+    return nodes
+
+
+def _locale_of(rel: str, locales: dict[str, Any]) -> tuple[str, str | None]:
+    m = _LOCALE.match(rel)
+    if m and m[2].lower() in locales:
+        return f"{m[1]}.md", locales[m[2].lower()]
+    return rel, None
+
+
+def _check_reserved(
+    file: str, rel: str, base: str, text: str, diagnostics: Diagnostics, limits: dict[str, Any]
+) -> None:
+    # Contract §3: the frontmatter size limit applies to reserved files too.
+    split = split_frontmatter(text, limits["maxFrontmatterBytes"])
+    if base == "index.md":
+        if not split.present:
+            return
+        keys = list(split.data) if isinstance(split.data, dict) else []
+        root_index = rel.lower() == "index.md"
+        if split.error or not root_index or any(k != "okf_version" for k in keys):
+            diagnostics.add(
+                "C004_RESERVED_FILE_INVALID",
+                "the bundle-root index.md may carry only an okf_version frontmatter key"
+                if root_index
+                else "index.md files carry no frontmatter",
+                file,
+            )
+        return
+    if split.present:
+        diagnostics.add("C004_RESERVED_FILE_INVALID", "log.md carries no frontmatter", file)
+    # Headings inside fenced code blocks are not headings.
+    fence = False
+    for i, line in enumerate(re.split(r"\r?\n", text)):
+        if re.match(r"^[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(```|~~~)", line):
+            fence = not fence
+        if fence:
+            continue
+        h = re.match(r"^##[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+(.*)\Z", line)
+        if h and not re.match(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}", h[1]):
+            diagnostics.add(
+                "C004_RESERVED_FILE_INVALID",
+                f'log.md date headings must start with an ISO 8601 date: "{h[1]}"',
+                file,
+                i + 1,
+            )
+
+
+def _source_ids(fm: dict[str, Any]) -> list[Any]:
+    sources = fm.get("sources")
+    return [get(s, "id") for s in (sources if isinstance(sources, list) else []) if truthy(get(s, "id"))]
+
+
+def _check_evidence(file: str, fm: dict[str, Any], diagnostics: Diagnostics) -> None:
+    evidence = get(fm.get("moca"), "evidence")
+    if not isinstance(evidence, list):
+        return
+    ids = _source_ids(fm)
+    for e in evidence:
+        source = get(e, "source")
+        if isinstance(source, str) and source not in ids:
+            diagnostics.add(
+                "C006_EVIDENCE_SOURCE_UNKNOWN",
+                f'evidence names source "{source}", which sources[] does not declare with that id',
+                file,
+            )
+
+
+def _verify_evidence(
+    file: str,
+    fm: dict[str, Any],
+    files: dict[str, str],
+    data: dict[str, bytes],
+    diagnostics: Diagnostics,
+    limits: dict[str, int],
+    source_text: dict[str, str],
+    budget: dict[str, Any],
+) -> list[EvidenceCheck]:
+    """Checks each moca.evidence selector against the cited file, when it is inside the package and checkable."""
+    evidence = get(fm.get("moca"), "evidence")
+    if not isinstance(evidence, list):
+        return []
+    declared = fm.get("sources")
+    sources: dict[Any, Any] = {}
+    for s in declared if isinstance(declared, list) else []:
+        sid = get(s, "id")
+        if truthy(sid) and isinstance(sid, (str, int, float, bool)):
+            sources[sid] = s
+    checks: list[EvidenceCheck] = []
+    for i, e in enumerate(evidence):
+        key = get(e, "source")
+        resource = get(sources.get(key), "resource") if isinstance(key, (str, int, float, bool)) else None
+        if not isinstance(resource, str) or not _PATH_REF.match(resource):
+            checks.append(EvidenceCheck(False))
+            continue
+        path, escapes = resolve_reference(file, resource)
+        if escapes or not path or path not in files or not path.startswith(_EVIDENCE_DIRS):
+            checks.append(EvidenceCheck(False))
+            continue
+        kind = source_kind(path)
+        selector = get(e, "selector")
+        if not kind or not isinstance(selector, dict):
+            checks.append(EvidenceCheck(True))
+            continue
+        if i >= limits["maxEvidencePerNode"] or len(data[path]) > limits["maxSourceBytesChecked"]:
+            checks.append(EvidenceCheck(True))
+            continue
+        if (
+            budget["checks"] >= limits["maxEvidenceChecksPerPackage"]
+            or budget["bytes"] + len(data[path]) > limits["maxEvidenceBytesPerPackage"]
+        ):
+            checks.append(EvidenceCheck(True))
+            continue
+        budget["checks"] += 1
+        budget["bytes"] += len(data[path])
+        if path not in source_text:
+            # Contract §7: a leading byte order mark is not part of an evidence source.
+            source_text[path] = data[path].decode("utf-8", errors="replace").removeprefix("\ufeff")
+        prepared = None
+        if selector.get("type") != "FragmentSelector":
+            key = f"{path}\u0000{kind}"
+            if key not in budget["prepared"]:
+                budget["prepared"][key] = normalised_text(source_text[path], kind)
+            prepared = budget["prepared"][key]
+        matched = check_selector(selector, source_text[path], kind, prepared)
+        if matched is False:
+            diagnostics.add(
+                "C011_EVIDENCE_SELECTOR_UNMATCHED",
+                f'evidence {selector.get("type")} for source "{key}" does not match {path}',
+                file,
+            )
+        checks.append(EvidenceCheck(True) if matched is None else EvidenceCheck(True, matched))
+    return checks
+
+
+def _check_window(file: str, fm: dict[str, Any], diagnostics: Diagnostics) -> None:
+    from ._js import parse_date
+
+    moca = fm.get("moca")
+    start, until = parse_date(get(moca, "valid_from")), parse_date(get(moca, "valid_until"))
+    if start is not None and until is not None and until <= start:
+        diagnostics.add("C010_VALIDITY_WINDOW_INVALID", "moca.valid_until must be later than moca.valid_from", file)
+
+
+_DRIVE = re.compile(r"^[A-Za-z]:[\\/]")
+
+
+def resolve_reference(from_file: str, ref: str) -> tuple[str | None, bool]:
+    """A package-relative reference from a node: (path, escapes). See :func:`resolve_reference_reason`."""
+    path, escapes, _ = resolve_reference_reason(from_file, ref)
+    return path, escapes
+
+
+def resolve_reference_reason(from_file: str, ref: str) -> tuple[str | None, bool, str]:
+    """A package-relative reference from a node: (path, unsafe, reason).
+
+    An absolute path or a drive prefix is unsafe, as is one that escapes the package root (C008);
+    so is a malformed percent-encoding, which never raises.
+    """
+    stripped = re.sub(r"^<|>\Z", "", ref).split("#")[0].split("?")[0]
+    try:
+        clean = decode_uri_component(stripped)
+    except ValueError:
+        return None, True, "has a malformed percent-encoding"
+    if clean == "":
+        return None, False, ""
+    if clean.startswith("/") or clean.startswith("\\") or _DRIVE.match(clean):
+        return None, True, "is absolute"
+    joined = posix_join(posix_dirname(from_file), clean)
+    if joined == ".." or joined.startswith("../") or joined.startswith("/"):
+        return None, True, "escapes the package root"
+    return normalize("NFC", joined), False, ""
+
+
+def _check_paths(file: str, fm: dict[str, Any], body: str, files: dict[str, str], diagnostics: Diagnostics) -> None:
+    sources = fm.get("sources")
+    for s in sources if isinstance(sources, list) else []:
+        r = get(s, "resource")
+        r = r if isinstance(r, str) else ""
+        if not _PATH_REF.match(r):
+            continue  # URLs and scope descriptors are not paths
+        path, escapes, reason = resolve_reference_reason(file, r)
+        if escapes:
+            diagnostics.add("C008_UNSAFE_PATH", f'source resource "{r}" {reason}', file)
+        elif path and path not in files:
+            diagnostics.add("C007_LINK_UNRESOLVED", f'source resource "{r}" does not resolve to a package file', file)
+
+    fence = False
+    for line in re.split(r"\r?\n", body):
+        if re.match(r"^[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(```|~~~)", line):
+            fence = not fence
+        if fence:
+            continue
+        for m in _LINK.finditer(re.sub(r"`[^`]*`", "", line)):
+            target = re.sub(r"^<|>\Z", "", m[1])
+            if (_SCHEME.match(target) and not _DRIVE.match(target)) or target.startswith("#"):
+                continue
+            path, escapes, reason = resolve_reference_reason(file, target)
+            if escapes:
+                diagnostics.add("C008_UNSAFE_PATH", f'link "{target}" {reason}', file)
+            elif path and path not in files:
+                diagnostics.add("C007_LINK_UNRESOLVED", f'link "{target}" does not resolve', file)

moca_reader/diagnostics.py

@@ -0,0 +1,45 @@
+"""Diagnostics: stable codes, a severity, a message, and where."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .codes import ERROR, WARNING, default_severity
+
+
+@dataclass
+class Diagnostic:
+    code: str
+    severity: str
+    message: str
+    file: str | None = None
+    line: int | None = None
+
+    def to_json(self) -> dict[str, object]:
+        out: dict[str, object] = {"code": self.code, "severity": self.severity, "message": self.message}
+        if self.file is not None:
+            out["file"] = self.file
+        if self.line is not None:
+            out["line"] = self.line
+        return out
+
+
+@dataclass
+class Diagnostics:
+    strict: bool = False
+    items: list[Diagnostic] = field(default_factory=list)
+
+    def add(self, code: str, message: str, file: str | None = None, line: int | None = None) -> Diagnostic:
+        severity = default_severity(code)
+        if self.strict and severity == WARNING:
+            severity = ERROR
+        entry = Diagnostic(code, severity, message, file, line)
+        self.items.append(entry)
+        return entry
+
+    def has(self, code: str) -> bool:
+        return any(d.code == code for d in self.items)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == ERROR for d in self.items)

moca_reader/digest.py

@@ -0,0 +1,92 @@
+"""The package digest, moca-digest-v2 (package spec §6).
+
+The SHA-256 of a BagIt-style payload manifest (RFC 8493 manifest-sha256.txt): one ``<hex>  <path>`` line
+per file, sorted by the UTF-8 bytes of the path. Computed, never declared: the same package as a
+directory, an archive or a host source has the same digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from .diagnostics import Diagnostics
+from .source import PackageSource
+from .unicode import normalize, simple_lowercase
+
+DIGEST_ALGORITHM = "moca-digest-v2"
+DIGEST_PATTERN = re.compile(r"^sha256:[a-f0-9]{64}\Z")
+MANIFEST = "moca.json"
+ATTESTATIONS_DIR = "attestations"
+
+
+def utf8(text: str) -> bytes:
+    """UTF-8 as JavaScript encodes it: a lone surrogate becomes U+FFFD."""
+    return text.encode("utf-16", "surrogatepass").decode("utf-16", "replace").encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def is_attestation_path(path: str) -> bool:
+    # Only entries under the attestations/ directory; a top-level file named
+    # `attestations` is ordinary package content and is digested.
+    return path.startswith(f"{ATTESTATIONS_DIR}/")
+
+
+def package_files(source: PackageSource, diagnostics: Diagnostics) -> tuple[bool, dict[str, str]]:
+    """The regular files that make up a package, NFC path -> stored path; P001-P003 when its identity is ambiguous."""
+    files: dict[str, str] = {}
+    folded: dict[str, str] = {}
+    ok = True
+    for entry in source.list():
+        if entry.kind in ("symlink", "other"):
+            what = "symbolic link" if entry.kind == "symlink" else "non-regular file"
+            diagnostics.add(
+                "P001_UNSUPPORTED_ENTRY",
+                f'"{entry.path}" is a {what}; packages may contain regular files only',
+                entry.path,
+            )
+            ok = False
+            continue
+        if entry.kind == "unreadable":
+            diagnostics.add("P002_UNREADABLE_ENTRY", f'"{entry.path}" could not be read', entry.path)
+            ok = False
+            continue
+        nfc = normalize("NFC", entry.path)
+        key = simple_lowercase(nfc)
+        if key in folded:
+            diagnostics.add(
+                "P003_PATH_COLLISION",
+                f'"{entry.path}" collides with "{folded[key]}" after NFC normalisation or case folding',
+                entry.path,
+            )
+            ok = False
+            continue
+        folded[key] = entry.path
+        files[nfc] = entry.path
+    return ok, files
+
+
+def manifest_path(path: str) -> str:
+    """A path as it appears in a BagIt manifest line: CR, LF and % percent-encoded (RFC 8493 §2.1.3)."""
+    return path.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def manifest_text(file_digests: dict[str, str]) -> str:
+    return "".join(
+        f"{hexd}  {manifest_path(p)}\n" for p, hexd in sorted(file_digests.items(), key=lambda kv: utf8(kv[0]))
+    )
+
+
+def compute_digest(files: dict[str, str], read: object) -> tuple[str, dict[str, str], str]:
+    """moca-digest-v2 over ``files`` (NFC path -> stored path), reading each with ``read(stored)``."""
+    reader = read  # a callable taking a stored path
+    file_digests: dict[str, str] = {}
+    for nfc, stored in files.items():
+        if is_attestation_path(nfc):
+            continue
+        file_digests[nfc] = sha256_hex(reader(stored))  # type: ignore[operator]
+    text = manifest_text(file_digests)
+    return f"sha256:{sha256_hex(utf8(text))}", file_digests, text

moca_reader/dsse.py

@@ -0,0 +1,97 @@
+"""DSSE (Dead Simple Signing Envelope): https://github.com/secure-systems-lab/dsse, with Ed25519 keys."""
+
+from __future__ import annotations
+
+import base64
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from .ed25519 import strict_encodings
+
+PAE_PREFIX = "DSSEv1"
+
+
+def pre_auth_encode(payload_type: str, payload: bytes) -> bytes:
+    """Pre-Authentication Encoding: ``DSSEv1 <len> <type> <len> <body>``, lengths in bytes."""
+    type_bytes = payload_type.encode("utf-8")
+    return b"".join([f"{PAE_PREFIX} {len(type_bytes)} ".encode(), type_bytes, f" {len(payload)} ".encode(), payload])
+
+
+def create_envelope(payload: bytes, payload_type: str, private_key_pem: str, keyid: str) -> dict[str, Any]:
+    key = serialization.load_pem_private_key(private_key_pem.encode(), password=None)
+    if not isinstance(key, Ed25519PrivateKey):
+        raise ValueError("DSSE envelopes are signed with Ed25519 keys")
+    signature = key.sign(pre_auth_encode(payload_type, payload))
+    return {
+        "payload": base64.b64encode(payload).decode(),
+        "payloadType": payload_type,
+        "signatures": [{"keyid": keyid, "sig": base64.b64encode(signature).decode()}],
+    }
+
+
+@dataclass
+class EnvelopeResult:
+    ok: bool
+    reason: str | None = None
+    payload: bytes | None = None
+    keyid: str | None = None
+
+
+_BASE64 = re.compile(r"^[A-Za-z0-9+/_-]*={0,2}\Z")
+
+
+def decode_base64(text: Any) -> bytes | None:
+    """Attestations §7: base64 (RFC 4648 §4) or base64url (§5), with or without padding; anything else is None."""
+    if not isinstance(text, str) or not _BASE64.match(text):
+        return None
+    body = text.rstrip("=")
+    if len(body) % 4 == 1 or (len(text) != len(body) and len(text) % 4 != 0):
+        return None
+    return base64.b64decode(body.replace("-", "+").replace("_", "/") + "=" * (-len(body) % 4))
+
+
+def verify_envelope(envelope: Any, resolve_public_key: Callable[[str], str | None]) -> EnvelopeResult:
+    if (
+        not isinstance(envelope, dict)
+        or not isinstance(envelope.get("payload"), str)
+        or not isinstance(envelope.get("payloadType"), str)
+        or not isinstance(envelope.get("signatures"), list)
+        or len(envelope["signatures"]) == 0
+    ):
+        return EnvelopeResult(False, "malformed DSSE envelope")
+    payload = decode_base64(envelope["payload"])
+    if payload is None:
+        return EnvelopeResult(False, "envelope payload is not valid base64")
+    pae = pre_auth_encode(envelope["payloadType"], payload)
+    for entry in envelope["signatures"]:
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("keyid"), str)
+            or not isinstance(entry.get("sig"), str)
+        ):
+            continue
+        signature = decode_base64(entry["sig"])
+        if signature is None:
+            continue
+        public_key_pem = resolve_public_key(entry["keyid"])
+        if not public_key_pem:
+            continue
+        try:
+            key = serialization.load_pem_public_key(public_key_pem.encode())
+            if not isinstance(key, Ed25519PublicKey):
+                continue
+            # Attestations §5: strict encodings first, so every Reader's library reaches the same answer.
+            raw = key.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+            if not strict_encodings(raw, signature):
+                continue
+            key.verify(signature, pae)
+        except (InvalidSignature, ValueError, TypeError):
+            continue
+        return EnvelopeResult(True, payload=payload, keyid=entry["keyid"])
+    return EnvelopeResult(False, "no signature verified against a trusted key")

moca_reader/ed25519.py

@@ -0,0 +1,83 @@
+"""Strict Ed25519 encodings (attestations §5).
+
+Ed25519 libraries disagree on edge cases: small-order and mixed-order points, and non-canonical encodings. MOCA
+removes the disagreement before a library verifies anything: the public key A and the signature's R must each be
+the canonical encoding of a point of prime order L, and S must be less than L. With those, the cofactored and
+cofactorless verification equations agree, so every Reader reaches the same answer.
+"""
+
+from __future__ import annotations
+
+P = 2**255 - 19
+L = 2**252 + 27742317777372353535851937790883648493
+_D = (-121665 * pow(121666, P - 2, P)) % P
+_SQRT_M1 = pow(2, (P - 1) // 4, P)
+
+_Point = tuple[int, int, int, int]
+_IDENTITY: _Point = (0, 1, 1, 0)
+
+
+def _add(p: _Point, q: _Point) -> _Point:
+    x1, y1, z1, t1 = p
+    x2, y2, z2, t2 = q
+    a = (y1 - x1) * (y2 - x2) % P
+    b = (y1 + x1) * (y2 + x2) % P
+    c = 2 * t1 * t2 * _D % P
+    d = 2 * z1 * z2 % P
+    e, f, g, h = b - a, d - c, d + c, b + a
+    return (e * f % P, g * h % P, f * g % P, e * h % P)
+
+
+def _mul(k: int, p: _Point) -> _Point:
+    q = _IDENTITY
+    while k:
+        if k & 1:
+            q = _add(q, p)
+        p = _add(p, p)
+        k >>= 1
+    return q
+
+
+def _is_identity(p: _Point) -> bool:
+    x, y, z, _ = p
+    return x % P == 0 and (y - z) % P == 0
+
+
+def _decode(encoded: bytes) -> _Point | None:
+    """RFC 8032 §5.1.3, refusing non-canonical encodings (y ≥ p, or x = 0 with the sign bit set)."""
+    if len(encoded) != 32:
+        return None
+    n = int.from_bytes(encoded, "little")
+    sign = n >> 255
+    y = n & ((1 << 255) - 1)
+    if y >= P:
+        return None
+    u = (y * y - 1) % P
+    v = (_D * y * y + 1) % P
+    x = u * pow(v, 3, P) * pow(u * pow(v, 7, P), (P - 5) // 8, P) % P
+    if (v * x * x - u) % P != 0:
+        x = x * _SQRT_M1 % P
+        if (v * x * x - u) % P != 0:
+            return None
+    if x == 0 and sign:
+        return None
+    if x & 1 != sign:
+        x = P - x
+    return (x, y, 1, x * y % P)
+
+
+def is_prime_order_point(encoded: bytes) -> bool:
+    """The canonical encoding of a point of order L: not the identity, no small-order component."""
+    point = _decode(encoded)
+    return point is not None and not _is_identity(point) and _is_identity(_mul(L, point))
+
+
+def strict_encodings(public_key: bytes, signature: bytes) -> bool:
+    """Attestations §5: A and R are canonical points of order L, and S < L."""
+    if len(signature) != 64:
+        return False
+    return (
+        int.from_bytes(signature[32:], "little") < L
+        and is_prime_order_point(public_key)
+        and is_prime_order_point(signature[:32])
+    )