provared 0.2.0__py3-none-any.whl

provared/der.py

@@ -0,0 +1,230 @@
+# A small, strict reader for DER, the byte layout that time-stamps and
+# certificates use (ITU-T X.690). It reads; it never writes. Anything not in
+# the one form DER allows is refused.
+
+import math
+import re
+
+from .encoding import Refusal, _days_from_civil
+
+
+def bad_stamp(why):
+    return Refusal('stamp-bad-data', f'A time-stamp is not laid out as its standard sets out: {why}')
+
+
+class TAG:
+    """The tags this reader meets."""
+
+    BOOLEAN = 0x01
+    INTEGER = 0x02
+    BIT_STRING = 0x03
+    OCTET_STRING = 0x04
+    NULL = 0x05
+    OID = 0x06
+    UTC_TIME = 0x17
+    GENERALIZED_TIME = 0x18
+    SEQUENCE = 0x30
+    SET = 0x31
+    CONTEXT_0 = 0xA0
+    CONTEXT_1 = 0xA1
+    CONTEXT_3 = 0xA3
+
+
+class Element:
+    """One element: "from_" is its first byte, "start" and "end" bound its content."""
+
+    __slots__ = ('tag', 'from_', 'start', 'end')
+
+    def __init__(self, tag, from_, start, end):
+        self.tag = tag
+        self.from_ = from_
+        self.start = start
+        self.end = end
+
+    def as_dict(self):
+        """The element as JavaScript gives it: {tag, from, start, end}."""
+        return {'tag': self.tag, 'from': self.from_, 'start': self.start, 'end': self.end}
+
+
+def read_element(data, at, end=None):
+    """Read the element that begins at "at". It must lie before "end"."""
+    if end is None:
+        end = len(data)
+    if at + 2 > end:
+        raise bad_stamp('it is cut short.')
+    tag = data[at]
+    if (tag & 0x1F) == 0x1F:
+        raise bad_stamp('it holds a tag of a kind that is not used here.')
+    length = data[at + 1]
+    start = at + 2
+    if length & 0x80:
+        count = length & 0x7F
+        # Never the indefinite form, and never more than four bytes of length.
+        if count == 0 or count > 4:
+            raise bad_stamp('it holds a length in a form that is not allowed.')
+        if start + count > end:
+            raise bad_stamp('it is cut short.')
+        length = 0
+        for i in range(count):
+            length = length * 256 + data[start + i]
+        if data[start] == 0 or length < 128:
+            raise bad_stamp('it holds a length that is not in its shortest form.')
+        start += count
+    if length > end - start:
+        raise bad_stamp('a part is longer than what holds it.')
+    return Element(tag, at, start, start + length)
+
+
+def children(data, parent, most=32):
+    """The elements inside a constructed element, in order. More than "most" is refused."""
+    out = []
+    at = parent.start
+    while at < parent.end:
+        if len(out) >= most:
+            raise bad_stamp('a part holds too many items.')
+        child = read_element(data, at, parent.end)
+        out.append(child)
+        at = child.end
+    return out
+
+
+def item(elements, i):
+    """elements[i], or None where there is no such item, as JavaScript gives undefined."""
+    return elements[i] if 0 <= i < len(elements) else None
+
+
+def expect(element, tag, what):
+    """Confirm an element's tag, and hand the element back."""
+    if element is None or element.tag != tag:
+        raise bad_stamp(f'{what} is missing or of the wrong kind.')
+    return element
+
+
+def content_of(data, element):
+    """The content bytes of an element."""
+    return bytes(data[element.start:element.end])
+
+
+def whole_of(data, element):
+    """The whole element, tag and length included."""
+    return bytes(data[element.from_:element.end])
+
+
+def hex_of(data, element):
+    """The content of an element as lower-case hexadecimal: how object identifiers are compared here."""
+    return bytes(data[element.start:element.end]).hex()
+
+
+_UTC_TIME = re.compile(r'([0-9][0-9])([0-9][0-9])([0-9][0-9])([0-9][0-9])([0-9][0-9])([0-9][0-9])Z')
+_GENERALIZED_TIME = re.compile(r'([0-9]{4})([0-9][0-9])([0-9][0-9])([0-9][0-9])([0-9][0-9])([0-9][0-9])(?:\.([0-9]{1,9}))?Z')
+
+
+def _days_in_month(y, m):
+    if m == 2:
+        return 29 if (y % 4 == 0 and (y % 100 != 0 or y % 400 == 0)) else 28
+    return 30 if m in (4, 6, 9, 11) else 31
+
+
+def time_of(data, element):
+    """A time, from the two forms DER allows: "YYMMDDHHMMSSZ" (UTCTime) and
+    "YYYYMMDDHHMMSS[.f]Z" (GeneralizedTime). Returns milliseconds."""
+    text = ''.join(chr(b) for b in data[element.start:element.end])
+    groups = None
+    if element.tag == TAG.UTC_TIME:
+        m = _UTC_TIME.fullmatch(text)
+        if m:
+            groups = list(m.groups()) + [None]
+            groups[0] = ('20' if int(groups[0]) < 50 else '19') + groups[0]
+    elif element.tag == TAG.GENERALIZED_TIME:
+        m = _GENERALIZED_TIME.fullmatch(text)
+        # DER allows no trailing zero in the fraction.
+        if m and not (m.group(7) and m.group(7).endswith('0')):
+            groups = list(m.groups())
+    if groups is None:
+        raise bad_stamp('a time is not written in the form DER allows.')
+    y, mo, d, h, mi, s = (int(g) for g in groups[:6])
+    fraction = groups[6]
+    # JavaScript's Date.UTC reads a year from 0 to 99 as 1900 to 1999, so
+    # such a year never names the moment it says, and is refused there.
+    if y <= 99 or not (1 <= mo <= 12) or not (1 <= d <= _days_in_month(y, mo)) or h > 23 or mi > 59 or s > 59:
+        raise bad_stamp('a time names a moment that does not exist.')
+    ms = ((_days_from_civil(y, mo, d) * 24 + h) * 60 + mi) * 60000 + s * 1000
+    if fraction:
+        ms += math.floor(float('0.' + fraction) * 1000)
+    return ms
+
+
+def ecdsa_to_raw(der, size):
+    """An ECDSA signature from its DER form (two whole numbers) to the two
+    numbers side by side, each of "size" bytes, as Web Crypto wants them.
+    size: 32 for P-256, 48 for P-384."""
+    der = bytes(der)
+    outer = expect(read_element(der, 0), TAG.SEQUENCE, 'the signature')
+    if outer.end != len(der):
+        raise bad_stamp('a signature has bytes left over.')
+    parts = children(der, outer, 2)
+    if len(parts) != 2:
+        raise bad_stamp('a signature does not hold two numbers.')
+    out = bytearray(size * 2)
+    for i, part in enumerate(parts):
+        expect(part, TAG.INTEGER, 'a number of the signature')
+        digits = content_of(der, part)
+        if len(digits) == 0 or digits[0] & 0x80:
+            raise bad_stamp('a signature holds a number that is not positive.')
+        if len(digits) > 1 and digits[0] == 0 and not (digits[1] & 0x80):
+            raise bad_stamp('a signature holds a number not in its shortest form.')
+        if digits[0] == 0:
+            digits = digits[1:]
+        if len(digits) > size:
+            raise bad_stamp('a signature holds a number that is too large.')
+        at = i * size + (size - len(digits))
+        out[at:at + len(digits)] = digits
+    return bytes(out)
+
+
+def validate_der(data, element):
+    """Walk a whole element and everything inside it, and refuse anything that
+    is not strict DER: a constructed part whose items do not fill it exactly,
+    a whole number or an object identifier that is not in its shortest form,
+    a truth value that is not written in the one way DER allows. Parts this
+    checker does not otherwise read are still read here, so that two checkers
+    cannot disagree about whether a time-stamp is well formed."""
+    budget = [4000]
+
+    def walk(e, depth):
+        budget[0] -= 1
+        if budget[0] < 0 or depth > 24:
+            raise bad_stamp('it holds too many parts, or parts nested too deeply.')
+        length = e.end - e.start
+        if e.tag & 0x20:
+            at = e.start
+            while at < e.end:
+                child = read_element(data, at, e.end)
+                walk(child, depth + 1)
+                at = child.end
+            return
+        if e.tag == TAG.INTEGER:
+            if length == 0:
+                raise bad_stamp('a whole number is empty.')
+            if length > 1:
+                first = data[e.start]
+                second = data[e.start + 1]
+                if (first == 0x00 and not (second & 0x80)) or (first == 0xFF and second & 0x80):
+                    raise bad_stamp('a whole number is not in its shortest form.')
+        elif e.tag == TAG.OID:
+            if length == 0 or data[e.end - 1] & 0x80:
+                raise bad_stamp('an object identifier is empty or cut short.')
+            for i in range(e.start, e.end):
+                if data[i] == 0x80 and (i == e.start or not (data[i - 1] & 0x80)):
+                    raise bad_stamp('an object identifier is not in its shortest form.')
+        elif e.tag == TAG.BOOLEAN:
+            if length != 1 or data[e.start] not in (0x00, 0xFF):
+                raise bad_stamp('a truth value is not written as DER allows.')
+        elif e.tag == TAG.NULL:
+            if length != 0:
+                raise bad_stamp('an empty value is not empty.')
+        elif e.tag == TAG.BIT_STRING:
+            if length == 0 or data[e.start] > 7:
+                raise bad_stamp('a string of bits is not written as DER allows.')
+
+    walk(element, 0)

provared/encoding.py

@@ -0,0 +1,278 @@
+# Bytes, base64url, the canonical form of JSON, fingerprints and times.
+#
+# Nothing here is specific to a kind of record. Each function does exactly
+# what its namesake in the JavaScript library's src/encoding.js does.
+
+import base64
+import hashlib
+import os
+import re
+import datetime as _datetime
+import time as _time
+
+from . import _js
+
+
+class Refusal(Exception):
+    """A refusal: a named reason why a record does not check. A failed check is
+    a normal answer, not a crash, so callers catch this and report its code."""
+
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def problem_from(e):
+    """Turn anything raised while checking into a problem to report. A Refusal
+    keeps its code. Anything else means the checker itself met something it
+    did not expect: that is reported as "check-failed" and is never a pass."""
+    if isinstance(e, Refusal):
+        return {'code': e.code, 'message': e.message}
+    return {'code': 'check-failed', 'message': 'The checker met something it did not expect here. This is treated as not intact.'}
+
+
+MAX_NUMBER = _js.MAX_SAFE_INTEGER
+"""The largest whole number the format allows (2^53 - 1)."""
+
+MAX_DEPTH = 8
+"""How deep the content of a record or a line of a book may nest."""
+
+
+def utf8(text):
+    """TextEncoder.encode: a surrogate without its other half becomes U+FFFD."""
+    try:
+        return text.encode('utf-8')
+    except UnicodeEncodeError:
+        return text.encode('utf-16-le', 'surrogatepass').decode('utf-16-le', 'replace').encode('utf-8')
+
+
+def from_utf8(data, code='not-json'):
+    """Strict UTF-8 decoding. A byte order mark is kept in the text."""
+    try:
+        return bytes(data).decode('utf-8', 'strict')
+    except UnicodeDecodeError:
+        raise Refusal(code, 'The bytes are not valid UTF-8 text.') from None
+
+
+def sha256(data):
+    """SHA-256 (FIPS 180-4)."""
+    return hashlib.sha256(bytes(data)).digest()
+
+
+# --- base64url (RFC 4648 section 5, no padding; RFC 7515 section 2) ---
+
+_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
+_LOOKUP = {c: i for i, c in enumerate(_ALPHABET)}
+
+
+def to_base64url(data):
+    data = bytes(data)
+    out = []
+    i = 0
+    n = len(data)
+    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
+    if i + 1 == n:
+        v = data[i] << 16
+        out.append(_ALPHABET[(v >> 18) & 63] + _ALPHABET[(v >> 12) & 63])
+    elif i + 2 == n:
+        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)
+
+
+_BASE64URL = re.compile(r'[A-Za-z0-9_-]*')
+
+
+def from_base64url(text):
+    """Strict decoding: refuses any character outside the alphabet, padding, an
+    impossible length, and stray bits in the last character. So one value has
+    exactly one text form."""
+    if not isinstance(text, str):
+        raise Refusal('bad-base64url', 'A base64url value must be text.')
+    if _js.utf16_length(text) % 4 == 1:
+        raise Refusal('bad-base64url', 'A base64url value has an impossible length.')
+    if not _BASE64URL.fullmatch(text):
+        raise Refusal('bad-base64url', 'A base64url value holds a character that is not allowed.')
+    # The bits of the last character that hold no byte must be zero: four of
+    # them after two characters, two after three.
+    rest = len(text) % 4
+    if rest and _LOOKUP[text[-1]] & (0x0F if rest == 2 else 0x03):
+        raise Refusal('bad-base64url', 'A base64url value has stray bits in its last character.')
+    return base64.urlsafe_b64decode(text + '=' * (-len(text) % 4))
+
+
+# --- the canonical form (RFC 8785, narrowed as the format description says) ---
+
+
+def _well_formed(text):
+    # Python joins a pair of surrogates written as escapes into one character,
+    # so any surrogate left is one without its other half.
+    chars = text
+    i = 0
+    n = len(chars)
+    while i < n:
+        o = ord(chars[i])
+        if 0xD800 <= o <= 0xDBFF:
+            if i + 1 < n and 0xDC00 <= ord(chars[i + 1]) <= 0xDFFF:
+                i += 2
+                continue
+            return False
+        if 0xDC00 <= o <= 0xDFFF:
+            return False
+        i += 1
+    return True
+
+
+def canonical_json(value, depth=0):
+    """Write a value in the canonical form: RFC 8785, narrowed to objects, lists,
+    strings and whole numbers from 0 to 2^53 - 1. For those types RFC 8785 is
+    exactly: members sorted by name (by UTF-16 code unit), strings as
+    JSON.stringify writes them, no spaces."""
+    if isinstance(value, str):
+        if not _well_formed(value):
+            raise Refusal('payload-not-canonical', 'A string is not well-formed Unicode.')
+        return _js.string(value)
+    if _js.is_number(value):
+        if not _js.is_safe_integer(value) or value < 0 or (isinstance(value, float) and value == 0 and str(value).startswith('-')):
+            raise Refusal('payload-not-canonical', 'A number must be a whole number from 0 to 9,007,199,254,740,991.')
+        return _js.number_text(value)
+    if not isinstance(value, (dict, list)):
+        raise Refusal('payload-not-canonical', 'Only objects, lists, strings and whole numbers are allowed.')
+    if depth >= MAX_DEPTH:
+        raise Refusal('payload-not-canonical', 'The content nests too deeply.')
+    if isinstance(value, list):
+        return '[' + ','.join(canonical_json(item, depth + 1) for item in value) + ']'
+    for name in value:
+        if not isinstance(name, str):
+            raise Refusal('payload-not-canonical', 'Only objects, lists, strings and whole numbers are allowed.')
+    names = _js.sort_strings(value.keys())
+    return '{' + ','.join(canonical_json(n, depth + 1) + ':' + canonical_json(value[n], depth + 1) for n in names) + '}'
+
+
+def parse_canonical(text, code='payload-not-canonical'):
+    """Read JSON text that must already be in the canonical form. The text is
+    parsed, written again canonically, and refused if the two differ. This
+    refuses a repeated member name, stray spaces and unusual number forms."""
+    try:
+        value = _js.parse(text)
+    except ValueError:
+        raise Refusal(code if code == 'payload-not-canonical' else 'not-json', 'The text is not JSON.') from None
+    try:
+        again = canonical_json(value)
+    except Refusal as e:
+        raise Refusal(code, e.message) from None
+    except RecursionError:
+        raise Refusal(code, 'The content nests too deeply.') from None
+    if again != text:
+        raise Refusal(code, 'The JSON is not in the canonical form (a repeated name, stray spaces, or members out of order).')
+    return value
+
+
+def count_characters(text):
+    """How many characters a text holds, counted as Unicode code points, so that
+    every implementation counts the same way."""
+    # The second half of a pair does not count again; Python already holds a
+    # pair as one character, and a lone second half is not counted, as in JavaScript.
+    return sum(1 for c in text if not (0xDC00 <= ord(c) <= 0xDFFF))
+
+
+def fingerprint(content_bytes):
+    """The fingerprint of a record: SHA-256 of its content bytes, in base64url."""
+    return to_base64url(sha256(content_bytes))
+
+
+# --- times (RFC 3339, UTC, to the second) ---
+
+_TIME = re.compile(r'([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})Z')
+
+
+def _days_from_civil(y, m, d):
+    y -= m <= 2
+    # Python's // rounds down, so no correction for years before 0 is needed.
+    era = y // 400
+    yoe = y - era * 400
+    doy = (153 * (m + (-3 if m > 2 else 9)) + 2) // 5 + d - 1
+    doe = yoe * 365 + yoe // 4 - yoe // 100 + doy
+    return era * 146097 + doe - 719468
+
+
+def _civil_from_days(z):
+    z += 719468
+    era = z // 146097
+    doe = z - era * 146097
+    yoe = (doe - doe // 1460 + doe // 36524 - doe // 146096) // 365
+    y = yoe + era * 400
+    doy = doe - (365 * yoe + yoe // 4 - yoe // 100)
+    mp = (5 * doy + 2) // 153
+    d = doy - (153 * mp + 2) // 5 + 1
+    m = mp + (3 if mp < 10 else -9)
+    return y + (m <= 2), m, d
+
+
+def _days_in_month(y, m):
+    if m == 2:
+        return 29 if (y % 4 == 0 and (y % 100 != 0 or y % 400 == 0)) else 28
+    return 30 if m in (4, 6, 9, 11) else 31
+
+
+def parse_time(text):
+    """Milliseconds since 1970, or None if the text is not a time in the one accepted form."""
+    if not isinstance(text, str):
+        return None
+    m = _TIME.fullmatch(text)
+    if not m:
+        return None
+    y, mo, d, h, mi, s = (int(g) for g in m.groups())
+    # Refuses dates that do not exist, such as 30 February.
+    if not (1 <= mo <= 12 and 1 <= d <= _days_in_month(y, mo) and h <= 23 and mi <= 59 and s <= 59):
+        return None
+    return ((_days_from_civil(y, mo, d) * 24 + h) * 60 + mi) * 60000 + s * 1000
+
+
+def nan_time(text):
+    """parseTime as JavaScript gives it: NaN, not None, for a text that is not
+    a time, so that every comparison with it is false, as in JavaScript."""
+    ms = parse_time(text)
+    return float('nan') if ms is None else ms
+
+
+MAX_TIME_MS = 8.64e15
+_EPOCH = _datetime.datetime(1970, 1, 1, tzinfo=_datetime.timezone.utc)
+
+
+def format_time(when):
+    """A time, written as YYYY-MM-DDTHH:MM:SSZ. Only a number of milliseconds
+    since 1970, or a datetime with a time zone (as a JavaScript Date), is
+    read: text, True or a datetime with no time zone would be read by rules
+    that differ from one device to another (as local time), so they are
+    refused."""
+    if isinstance(when, _datetime.datetime) and when.tzinfo is not None:
+        when = (when - _EPOCH) // _datetime.timedelta(milliseconds=1)
+    if not _js.finite(when) or abs(when) > MAX_TIME_MS:
+        raise ValueError('Invalid time value')
+    # new Date() cuts a fraction of a millisecond off towards zero.
+    ms = int(when)
+    days, rest = divmod(ms, 86400000)
+    y, mo, d = _civil_from_days(days)
+    secs = rest // 1000
+    h, secs = divmod(secs, 3600)
+    mi, s = divmod(secs, 60)
+    year = '%04d' % y if 0 <= y <= 9999 else ('+' if y > 0 else '-') + '%06d' % abs(y)
+    # As JavaScript does it: the first 19 characters of toISOString(), and
+    # "Z". For a year outside 0 to 9999 that cuts off the seconds.
+    iso = '%s-%02d-%02dT%02d:%02d:%02d.000Z' % (year, mo, d, h, mi, s)
+    return iso[:19] + 'Z'
+
+
+def now_ms():
+    """Date.now()"""
+    return _time.time_ns() // 1_000_000
+
+
+def random_id():
+    """16 random bytes in base64url: the unique number of a record."""
+    return to_base64url(os.urandom(16))

provared/fields.py

@@ -0,0 +1,95 @@
+# Small checks on the fields of a record's content. Each raises a Refusal
+# with the code "bad-field" and says which field and why.
+
+import re
+
+from . import _js
+from .actions import is_unknown_reserved
+from .encoding import MAX_NUMBER, Refusal, count_characters, from_base64url, parse_time
+
+
+def fail(path, why):
+    return Refusal('bad-field', f'{path}: {why}')
+
+
+def members(value, required, optional, path):
+    """An object must hold every required member, and no member that is neither
+    required nor optional. An unknown member is refused."""
+    if not isinstance(value, dict):
+        raise fail(path, 'must be an object.')
+    for name in required:
+        if name not in value:
+            raise fail(path, f'"{name}" is missing.')
+    for name in value:
+        if name not in required and name not in optional:
+            raise fail(path, 'holds a member that is not known.')
+
+
+def text(value, minimum, maximum, path):
+    # The quick test on the raw length keeps a huge text from being counted.
+    if not isinstance(value, str) or _js.utf16_length(value) > maximum * 2 or count_characters(value) < minimum or count_characters(value) > maximum:
+        raise fail(path, f'must be text of {minimum} to {maximum} characters.')
+
+
+def whole_number(value, path):
+    if not _js.is_safe_integer(value) or value < 0 or value > MAX_NUMBER:
+        raise fail(path, 'must be a whole number, 0 or more.')
+
+
+def list_of(value, minimum, maximum, path):
+    if not isinstance(value, list) or len(value) < minimum or len(value) > maximum:
+        raise fail(path, f'must be a list of {minimum} to {maximum} items.')
+
+
+_NAME = re.compile(r'[a-z0-9][a-z0-9._-]{0,63}')
+_UNIT = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,15}')
+
+
+def short_name(value, path):
+    """An action name, or the id of a service."""
+    if not isinstance(value, str) or not _NAME.fullmatch(value):
+        raise fail(path, 'must be 1 to 64 lower-case letters, digits, full stops, hyphens or underscores.')
+
+
+def action_name(value, path):
+    """An action name. Names that begin "provared." must be on the shared list."""
+    short_name(value, path)
+    if is_unknown_reserved(value):
+        raise fail(path, 'names that begin "provared." are reserved, and this one is not on the shared list.')
+
+
+def unit(value, path):
+    if not isinstance(value, str) or not _UNIT.fullmatch(value):
+        raise fail(path, 'must be 1 to 16 letters, digits, full stops, hyphens or underscores, with no spaces.')
+
+
+def label(value, path):
+    """A label chosen by whoever wrote the record. Never checked against anything."""
+    text(value, 1, 200, path)
+
+
+def _base64url_of_length(value, length, path, what):
+    try:
+        decoded = from_base64url(value)
+    except Refusal:
+        raise fail(path, f'must be {what}.') from None
+    if len(decoded) != length:
+        raise fail(path, f'must be {what}.')
+
+
+def id_(value, path):
+    """A unique number: 16 bytes in base64url."""
+    _base64url_of_length(value, 16, path, 'a unique number of 16 bytes in base64url')
+
+
+def fingerprint_text(value, path):
+    """A fingerprint: SHA-256 in base64url."""
+    _base64url_of_length(value, 32, path, 'a SHA-256 fingerprint in base64url')
+
+
+def time(value, path):
+    """The time in milliseconds."""
+    ms = parse_time(value)
+    if ms is None:
+        raise fail(path, 'must be a time written as YYYY-MM-DDTHH:MM:SSZ.')
+    return ms