pow-core 0.2.0__py3-none-any.whl

pow_core/__init__.py

@@ -0,0 +1,184 @@
+"""pow_core: the Proof of Work protocol core for Python agents (SPEC v1.5).
+
+A byte-compatible port of ``@pow/core``'s protocol layer: canonical JSON and
+the wire rule, base64url, Ed25519 device keys, ``pw1:`` accounts, event ids
+and signatures, per-kind body validation for all 30 kinds, root-signed
+delegations and revocations, wallet and Offline ID links (EIP-191 recovery
+included), sponsorships, validity classification, the one-active-per-day
+rule, sync buckets, the pw/1 gossip codec (including transport binding) and a
+SQLite EventStore. ``packages/core/vectors/*.json`` are the shared test
+vectors both ports reproduce byte for byte.
+"""
+
+from __future__ import annotations
+
+from . import testing
+from .active import ActiveBeacons, ActiveOutcome, ActiveStats, beats
+from .base64url import base64url_decode, base64url_encode, is_base64url
+from .bodies import KINDS, LINK_TYPES, OPERATOR_LABELS, REACTIONS, RECOMMENDED_LABELS, ROOT_SIGNED_KINDS, SCOPES, SUBSCRIBE_TYPES, required_scope, validate_body
+from .budget import VerificationBudget
+from .buckets import (
+    ACTIVE_PREFIX,
+    CHILD_KINDS,
+    IDENTITY_KINDS,
+    BucketName,
+    BucketPlacement,
+    Digest,
+    bucket_of,
+    digest_of,
+    parent_of,
+    parse_bucket,
+)
+from .canonical import canonical_bytes, canonicalize, has_lone_surrogate, parse_strict_json
+from .copresence import copresence_message, new_copresence_nonce, sign_copresence, verify_copresence
+from .crypto import (
+    DeviceKeyPair,
+    device_key_from_secret,
+    generate_device_key,
+    is_strong_public_key,
+    sha256,
+    sign_bytes,
+    verify_bytes,
+)
+from .day import day_of, day_start
+from .delegation import AuthStatus, DelegationIndex, DelegationRecord, IndexAddResult, TransportBinding
+from .eip191 import (
+    OfflineEoaVerifier,
+    address_from_private_key,
+    address_from_public_key,
+    create_offline_eoa_verifier,
+    keccak256,
+    personal_message_hash,
+    recover_personal_message_signer,
+    sign_personal_message,
+)
+from .errors import ErrorCode, Issue, ProtocolError, issue
+from .event import (
+    Envelope,
+    VerifyResult,
+    build_event,
+    create_event,
+    event_id,
+    expected_refs,
+    sign_event,
+    unsigned_bytes,
+    verify_event,
+    verify_event_cached,
+)
+from .formats import (
+    ACCOUNT_PREFIX,
+    EXTERNAL_LINK_TYPES,
+    RESERVED_SLUGS,
+    account_id_of,
+    account_root,
+    code_point_length,
+    format_caip10_account,
+    is_account,
+    is_board_slug,
+    is_caip10_account,
+    is_ens_like_name,
+    is_event_id,
+    is_evm_address,
+    is_external_link_type,
+    is_external_proof,
+    is_external_ref,
+    is_gist_id,
+    is_hash32,
+    is_http_url,
+    is_iso_day,
+    is_label_slug,
+    is_offline_id_subject,
+    is_op_address,
+    is_proof_token,
+    is_public_key_text,
+    is_signature_text,
+    is_tag,
+    is_tx_ref,
+    is_uint256_decimal,
+    is_wallet_sig_hex,
+    parse_caip10_account,
+)
+from .limits import LIMITS, MAX_SAFE_INTEGER, WALLET_LINK_CHAIN_IDS, is_wallet_link_chain
+from .links import LinkAddResult, LinkIndex, LinkRecord
+from .messages import MAX_WIRE_HOPS, PROTOCOL_VERSION, batch_events, chunk_ids, decode_message, encode_message, encoded_size
+from .recovery import (
+    RECOVERY_APPROVAL_TAG,
+    RECOVERY_CANCEL_TAG,
+    RECOVERY_PLAN_TAG,
+    REROOT_TAG,
+    guardian_key,
+    recovery_approval_message,
+    recovery_cancel_message,
+    recovery_plan_id,
+    recovery_plan_message,
+    recovery_root_sig_problem,
+    reroot_id,
+    reroot_message,
+    sign_recovery_cancel,
+    sign_recovery_plan,
+    sign_reroot,
+)
+from .signing import (
+    DELEGATION_SIGNING_TAG,
+    LINK_SIGNING_TAG,
+    LINK_SIGNING_TAG_V2,
+    REVOCATION_SIGNING_TAG,
+    TRANSPORT_BINDING_TAG,
+    TransportBindingStatement,
+    delegation_signing_payload,
+    link_signing_payload,
+    link_signing_payload_v2,
+    new_nonce,
+    policy_hash,
+    revocation_signing_payload,
+    sign_delegation_body,
+    sign_revocation_body,
+    sign_transport_binding,
+    transport_binding_message,
+    verify_root_sig,
+    verify_transport_binding,
+)
+from .sponsorship import DEFAULT_SPONSOR_CAPACITY, SponsorshipIndex, SponsorshipState
+from .store import Query, SqliteEventStore
+from .transport import Link, Transport, link_local
+from .validity import CONTEXTUAL_CODES, Validation, Validity, classify_event, validate_event, validity_of
+from .wallet import ExternalLinkVerifier, OfflineIdVerifier, WalletSignatureVerifier, WalletVerdict
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ACCOUNT_PREFIX", "ACTIVE_PREFIX", "ActiveBeacons", "ActiveOutcome", "ActiveStats", "AuthStatus",
+    "BucketName", "BucketPlacement", "CHILD_KINDS", "CONTEXTUAL_CODES", "DEFAULT_SPONSOR_CAPACITY",
+    "DELEGATION_SIGNING_TAG", "DelegationIndex", "DelegationRecord", "DeviceKeyPair", "Digest", "Envelope",
+    "ErrorCode", "IDENTITY_KINDS", "IndexAddResult", "Issue", "KINDS", "LIMITS", "LINK_SIGNING_TAG", "LINK_SIGNING_TAG_V2", "Link", "link_local", "WALLET_LINK_CHAIN_IDS", "is_wallet_link_chain",
+    "LinkAddResult", "LinkIndex", "LinkRecord", "MAX_SAFE_INTEGER", "OfflineEoaVerifier", "OfflineIdVerifier",
+    "OPERATOR_LABELS", "PROTOCOL_VERSION", "ProtocolError", "Query", "RECOMMENDED_LABELS", "RESERVED_SLUGS",
+    "REVOCATION_SIGNING_TAG", "SCOPES", "SponsorshipIndex", "SponsorshipState", "SqliteEventStore",
+    "TRANSPORT_BINDING_TAG", "Transport", "TransportBinding", "TransportBindingStatement", "Validation",
+    "Validity", "VerificationBudget", "VerifyResult", "WalletSignatureVerifier", "WalletVerdict",
+    "account_id_of", "account_root", "address_from_private_key", "address_from_public_key",
+    "base64url_decode", "base64url_encode", "batch_events", "beats", "bucket_of", "build_event",
+    "canonical_bytes", "canonicalize", "chunk_ids", "classify_event", "code_point_length",
+    "copresence_message", "create_event", "create_offline_eoa_verifier", "day_of", "day_start",
+    "decode_message", "delegation_signing_payload", "device_key_from_secret", "digest_of", "encode_message",
+    "encoded_size", "event_id", "expected_refs", "format_caip10_account", "generate_device_key",
+    "has_lone_surrogate", "is_account", "is_base64url", "is_board_slug", "is_caip10_account",
+    "is_ens_like_name", "is_event_id", "is_evm_address", "is_hash32", "is_http_url", "is_iso_day",
+    "is_label_slug", "is_offline_id_subject", "is_op_address", "is_proof_token", "is_public_key_text",
+    "is_signature_text", "is_strong_public_key", "is_tag", "is_tx_ref", "is_uint256_decimal",
+    "is_wallet_sig_hex", "issue", "keccak256", "link_signing_payload", "link_signing_payload_v2", "new_copresence_nonce", "new_nonce",
+    "parent_of", "parse_bucket", "parse_caip10_account", "parse_strict_json", "personal_message_hash",
+    "policy_hash", "recover_personal_message_signer", "required_scope", "revocation_signing_payload",
+    "sha256", "sign_bytes", "sign_copresence", "sign_delegation_body", "sign_event", "sign_personal_message",
+    "sign_revocation_body", "sign_transport_binding", "testing", "transport_binding_message",
+    "unsigned_bytes", "validate_body", "validate_event", "validity_of", "verify_bytes", "verify_copresence",
+    "verify_event", "verify_event_cached", "verify_root_sig", "verify_transport_binding",
+    # recovery statements (SPEC §2) and gossip hop metadata (SPEC §11 item 3)
+    "MAX_WIRE_HOPS", "RECOVERY_APPROVAL_TAG", "RECOVERY_CANCEL_TAG", "RECOVERY_PLAN_TAG", "REROOT_TAG",
+    "ROOT_SIGNED_KINDS", "guardian_key", "recovery_approval_message", "recovery_cancel_message",
+    "recovery_plan_id", "recovery_plan_message", "recovery_root_sig_problem", "reroot_id", "reroot_message",
+    "sign_recovery_cancel", "sign_recovery_plan", "sign_reroot",
+    # v1.9: external link types (SPEC §18.6) and the reaction, collection, subscribe and poll_vote kinds
+    "EXTERNAL_LINK_TYPES", "ExternalLinkVerifier", "LINK_TYPES", "REACTIONS", "SUBSCRIBE_TYPES",
+    "is_external_link_type", "is_external_proof", "is_external_ref", "is_gist_id",
+]

pow_core/active.py

@@ -0,0 +1,311 @@
+"""The one-``active``-per-(account, day) rule (SPEC §5.2, §12) for a Python node.
+
+The TypeScript gossip engine applies this rule inside ``GossipEngine``
+(``ingestActive`` / ``settleStoredActive``). The Python port has no gossip
+engine yet, so the same rule lives here, over any store that has ``put``,
+``query`` and ``remove`` (:class:`~pow_core.store.SqliteEventStore` does):
+
+- only beacons that classify ``valid`` compete. An ``unlinked`` beacon is
+  neither stored nor forwarded; it is held in memory (bounded, FIFO) and
+  re-ingested when a delegation for its author arrives, so no stranger's key
+  can take an account's day;
+- among valid beacons for one (account, day) the smallest ``created_at`` wins,
+  ties broken by the smaller ``id`` (string order). Arrival order never matters;
+- admitting the winner removes stored losers, and losers are refused
+  afterwards, so ``active/<day>`` digests converge across nodes;
+- the rule also applies to beacons other code wrote straight into the store:
+  when the store has ``subscribe`` (SqliteEventStore does) and ``watch_store``
+  is left on, every new ``active`` event the store reports is settled
+  automatically, as the TypeScript engine's ``onStoreEvent`` does; otherwise
+  callers that write beacons directly must call
+  :meth:`ActiveBeacons.settle_stored` themselves.
+
+Background work (store settles, re-ingests after a delegation arrives) runs on
+the event loop that is running when it is triggered; a delegation added with
+no loop running is noted and its beacons are re-ingested at the next
+``ingest``/``settle_stored`` call (or by :meth:`ActiveBeacons.retry_held`).
+Use one ``ActiveBeacons`` from one event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Callable, Literal
+
+from .day import day_start
+from .delegation import DelegationIndex
+from .links import LinkIndex
+from .validity import classify_event, validate_event
+
+Envelope = dict[str, Any]
+
+#: What :meth:`ActiveBeacons.ingest` did with a beacon.
+ActiveOutcome = Literal["new", "dup", "lost", "held", "invalid", "ignored"]
+
+#: Unlinked beacons held in memory, as the TypeScript engine's MAX_HELD_ACTIVE.
+MAX_HELD_ACTIVE = 4096
+_DAY_MS = 86_400_000
+
+
+def beats(x: Envelope, y: Envelope) -> bool:
+    """SPEC §5.2 tie-break: of two valid beacons for one (account, day), the smaller (created_at, id) wins."""
+    return bool(x["created_at"] < y["created_at"] or (x["created_at"] == y["created_at"] and x["id"] < y["id"]))
+
+
+@dataclass
+class ActiveStats:
+    """Counters, named after the TypeScript ``GossipStats`` fields."""
+
+    #: beacons that lost the tie-break: refused, or removed when the winner arrived
+    active_duplicates: int = 0
+    #: stored beacons removed because a winning beacon for their (account, day) arrived
+    active_replaced: int = 0
+    #: unlinked beacons held in memory until their delegation arrives
+    active_held: int = 0
+
+
+@dataclass
+class _KeyLock:
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    users: int = 0
+
+
+class ActiveBeacons:
+    """Applies the SPEC §5.2 activity rule to one store.
+
+    ``store`` needs ``put``, ``query`` and ``remove`` (a store without
+    ``remove`` cannot drop a losing beacon, so its ``active/`` digests would not
+    converge). ``now`` (ms) defaults to the system clock for the future bound.
+    ``watch_store`` (default on) settles beacons other code puts into a store
+    that has ``subscribe``. :meth:`close` detaches from the store and the index.
+    """
+
+    def __init__(
+        self,
+        store: Any,
+        delegations: DelegationIndex,
+        *,
+        links: LinkIndex | None = None,
+        max_held: int = MAX_HELD_ACTIVE,
+        now: Callable[[], int] | None = None,
+        watch_store: bool = True,
+    ) -> None:
+        if not callable(getattr(store, "remove", None)):
+            raise TypeError("the store needs remove(id): losing beacons must be dropped for active/ digests to converge")
+        self._store = store
+        self._delegations = delegations
+        self._links = links
+        self._max_held = max_held
+        self._now = now
+        self._held: OrderedDict[str, Envelope] = OrderedDict()
+        self._locks: dict[str, _KeyLock] = {}
+        self._tasks: set[asyncio.Task[Any]] = set()
+        # held beacons whose delegation arrived while no loop was running
+        self._ready: set[str] = set()
+        # ids this object is putting, so its own store writes are not re-settled
+        self._own_puts: set[str] = set()
+        self.stats = ActiveStats()
+        self._detach: list[Callable[[], None]] = [delegations.on_change(self._on_delegation)]
+        subscribe = getattr(store, "subscribe", None)
+        if watch_store and callable(subscribe):
+            self._detach.append(subscribe(self._on_store_event))
+
+    def close(self) -> None:
+        """Stops watching the store and the delegation index (scheduled work still finishes; see :meth:`drain`)."""
+        for off in self._detach:
+            off()
+        self._detach.clear()
+
+    @property
+    def lock_count(self) -> int:
+        """(account, day) decisions in progress or waiting; zero when idle."""
+        return len(self._locks)
+
+    @property
+    def held_count(self) -> int:
+        """Unlinked beacons held in memory."""
+        return len(self._held)
+
+    def is_held(self, eid: str) -> bool:
+        """True while a beacon is held waiting for its delegation."""
+        return eid in self._held
+
+    async def ingest(self, e: Any) -> ActiveOutcome:
+        """Validates a beacon and applies the rule; "new" means it was stored and should be forwarded."""
+        if not isinstance(e, dict) or e.get("kind") != "active":
+            return "ignored"
+        self._kick_ready()
+        v = await validate_event(e, delegations=self._delegations, links=self._links, now=self._now() if self._now else None)
+        if v.validity == "invalid":
+            return "invalid"
+        assert v.event is not None
+        if v.validity == "unlinked":
+            self._hold(v.event)
+            return "held"
+        return await self._admit(v.event)
+
+    async def _admit(self, e: Envelope) -> ActiveOutcome:
+        async with self._locked(e):
+            winner, losers = await self._contest(e)
+            if winner is not e:
+                self.stats.active_duplicates += 1
+                return "lost"
+            self._own_puts.add(e["id"])
+            try:
+                r = await self._store.put(e)
+            finally:
+                self._own_puts.discard(e["id"])
+            if r == "dup":
+                return "dup"
+            if r != "new":
+                return "invalid"
+            await self._drop(losers)
+            return "new"
+
+    async def settle_stored(self, e: Envelope) -> bool:
+        """The rule for a beacon other code wrote straight into the store.
+
+        An unlinked beacon is removed (and held); a losing one is removed; a
+        winner removes stored losers. True when ``e`` stays (and should be
+        forwarded). An invalid beacon is left alone and not forwarded.
+        """
+        if e.get("kind") != "active":
+            return True
+        self._kick_ready()
+        v = await validate_event(e, delegations=self._delegations, links=self._links, now=self._now() if self._now else None)
+        if v.validity == "invalid":
+            return False
+        if v.validity == "unlinked":
+            self._hold(e)
+            await self._store.remove(e["id"])
+            return False
+        async with self._locked(e):
+            winner, losers = await self._contest(e)
+            if winner is not e:
+                await self._drop([e["id"]])
+                return False
+            await self._drop(losers)
+            return True
+
+    async def _contest(self, e: Envelope) -> tuple[Envelope, list[str]]:
+        # The winner among e and the stored beacons for its (account, day), and
+        # the stored beacons that must go if e is admitted (losers, plus any
+        # that no longer classify valid, e.g. after a revocation).
+        day = e["body"]["day"]
+        start = day_start(day)
+        stored = await self._store.query(kinds=["active"], account=e["account"], since=start, until=start + _DAY_MS - 1)
+        same = [x for x in stored if x["id"] != e["id"] and x["body"]["day"] == day]
+        winner = e
+        for x in same:
+            if classify_event(x, self._delegations, self._links).validity == "valid" and beats(x, winner):
+                winner = x
+        return winner, ([x["id"] for x in same] if winner is e else [])
+
+    async def _drop(self, ids: list[str]) -> None:
+        for eid in ids:
+            if await self._store.remove(eid):
+                self.stats.active_replaced += 1
+                self.stats.active_duplicates += 1
+
+    @contextlib.asynccontextmanager
+    async def _locked(self, e: Envelope) -> AsyncIterator[None]:
+        # One decision at a time per (account, day). The entry is dropped once
+        # nobody holds or waits for it (as the TypeScript withActiveLock), so
+        # the map only ever holds keys with work in progress.
+        k = f"{e['account']}|{e['body']['day']}"
+        entry = self._locks.get(k)
+        if entry is None:
+            entry = self._locks[k] = _KeyLock()
+        entry.users += 1
+        try:
+            async with entry.lock:
+                yield
+        finally:
+            entry.users -= 1
+            if entry.users == 0 and self._locks.get(k) is entry:
+                del self._locks[k]
+
+    def _spawn(self, loop: asyncio.AbstractEventLoop, coro: Any) -> None:
+        # Keep a reference so the task is not garbage-collected mid-flight.
+        task = loop.create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    def _on_store_event(self, e: Envelope) -> None:
+        # A beacon other code wrote into the store (SPEC §5.2: the rule covers
+        # local writes too). Our own puts were already decided under the lock.
+        if e.get("kind") != "active" or e.get("id") in self._own_puts:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return  # store.put is a coroutine, so this only happens off-loop; settle_stored by hand
+        self._spawn(loop, self._settle_quietly(e))
+
+    async def _settle_quietly(self, e: Envelope) -> None:
+        try:
+            await self.settle_stored(e)
+        except Exception:  # noqa: BLE001 - a background settle must never raise into the loop
+            pass
+
+    def _kick_ready(self) -> None:
+        # Re-ingest held beacons whose delegation arrived while no loop ran.
+        if not self._ready:
+            return
+        ids, self._ready = self._ready, set()
+        loop = asyncio.get_running_loop()
+        for eid in ids:
+            x = self._held.pop(eid, None)
+            if x is not None:
+                self._spawn(loop, self._reingest(x))
+
+    def _hold(self, e: Envelope) -> None:
+        if e["id"] in self._held:
+            return
+        if len(self._held) >= self._max_held:
+            # Evicted beacons are not lost: a later anti-entropy round lists them again.
+            evicted, _ = self._held.popitem(last=False)
+            self._ready.discard(evicted)
+        self._held[e["id"]] = e
+        self.stats.active_held += 1
+
+    def _on_delegation(self, d: Envelope) -> None:
+        if d.get("kind") != "delegation":
+            return
+        device = d["body"]["device"]
+        retry = [x for x in self._held.values() if x["account"] == d["account"] and x["author"] == device]
+        if not retry:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No loop: the next ingest/settle_stored (or retry_held) re-ingests them.
+            self._ready.update(x["id"] for x in retry)
+            return
+        for x in retry:
+            self._held.pop(x["id"], None)
+            self._spawn(loop, self._reingest(x))
+
+    async def _reingest(self, e: Envelope) -> None:
+        try:
+            await self.ingest(e)
+        except Exception:  # noqa: BLE001 - a background re-check must never raise into the loop
+            pass
+
+    async def retry_held(self) -> int:
+        """Re-ingests held beacons; returns how many were stored."""
+        stored = 0
+        self._ready.clear()
+        for e in list(self._held.values()):
+            self._held.pop(e["id"], None)
+            if await self.ingest(e) == "new":
+                stored += 1
+        return stored
+
+    async def drain(self) -> None:
+        """Waits for re-ingests scheduled by arriving delegations (tests and shutdown)."""
+        while self._tasks:
+            await asyncio.gather(*list(self._tasks), return_exceptions=True)

pow_core/base64url.py

@@ -0,0 +1,77 @@
+"""Strict unpadded base64url (RFC 4648 §5).
+
+Decoding rejects padding, foreign characters, impossible lengths and non-zero
+trailing bits, so every byte string has exactly one textual form; otherwise two
+spellings of one key or id could both verify. The standard library decoder is
+lenient on all of those, hence the hand-rolled codec.
+"""
+
+from __future__ import annotations
+
+from .errors import ProtocolError
+
+_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+_LOOKUP = {c: i for i, c in enumerate(_ALPHABET)}
+
+
+def base64url_encode(data: bytes) -> str:
+    """Encodes bytes as unpadded base64url."""
+    out: list[str] = []
+    n = len(data)
+    i = 0
+    while i + 2 < n:
+        v = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2]
+        out.append(_ALPHABET[(v >> 18) & 63] + _ALPHABET[(v >> 12) & 63] + _ALPHABET[(v >> 6) & 63] + _ALPHABET[v & 63])
+        i += 3
+    rest = n - i
+    if rest == 1:
+        v = data[i] << 16
+        out.append(_ALPHABET[(v >> 18) & 63] + _ALPHABET[(v >> 12) & 63])
+    elif rest == 2:
+        v = (data[i] << 16) | (data[i + 1] << 8)
+        out.append(_ALPHABET[(v >> 18) & 63] + _ALPHABET[(v >> 12) & 63] + _ALPHABET[(v >> 6) & 63])
+    return "".join(out)
+
+
+def base64url_decode(text: str) -> bytes:
+    """Decodes strict unpadded base64url.
+
+    Raises :class:`ProtocolError` with ``E_B64_LENGTH``, ``E_B64_CHAR`` or
+    ``E_B64_NONCANONICAL`` (checked in that order, as the TypeScript core does).
+    """
+    if len(text) % 4 == 1:
+        raise ProtocolError("E_B64_LENGTH", "impossible base64url length")
+    vals: list[int] = []
+    for i, c in enumerate(text):
+        v = _LOOKUP.get(c)
+        if v is None:
+            raise ProtocolError("E_B64_CHAR", f"invalid base64url character at {i}")
+        vals.append(v)
+    full, rest = divmod(len(vals), 4)
+    out = bytearray()
+    i = 0
+    for _ in range(full):
+        n = (vals[i] << 18) | (vals[i + 1] << 12) | (vals[i + 2] << 6) | vals[i + 3]
+        out += bytes(((n >> 16) & 255, (n >> 8) & 255, n & 255))
+        i += 4
+    if rest == 2:
+        if vals[i + 1] & 0x0F:
+            raise ProtocolError("E_B64_NONCANONICAL", "non-zero trailing bits")
+        out.append(((vals[i] << 2) | (vals[i + 1] >> 4)) & 255)
+    elif rest == 3:
+        if vals[i + 2] & 0x03:
+            raise ProtocolError("E_B64_NONCANONICAL", "non-zero trailing bits")
+        n = (vals[i] << 10) | (vals[i + 1] << 4) | (vals[i + 2] >> 2)
+        out += bytes(((n >> 8) & 255, n & 255))
+    return bytes(out)
+
+
+def is_base64url(text: object, byte_length: int | None = None) -> bool:
+    """True when ``text`` is strict base64url, optionally of exactly ``byte_length`` bytes."""
+    if not isinstance(text, str):
+        return False
+    try:
+        b = base64url_decode(text)
+    except ProtocolError:
+        return False
+    return byte_length is None or len(b) == byte_length