provared 0.2.0__py3-none-any.whl

provared/__init__.py

@@ -0,0 +1,60 @@
+# Provared, draft version 0: proof of what an AI agent was allowed to do,
+# and what it then did. Evidence, not a verdict.
+#
+# The Python version of the JavaScript library, built in stages. It gives
+# the same answers, case for case, as the shared test files in
+# test-vectors/ at the top of the repository show. One difference: the
+# package "cryptography" has no SLH-DSA yet, so a seal's third signature is
+# reported as not checked on this device, and never as a pass.
+#
+# Checking:  check_book, check_show, check_slip
+#            open_checker (a checker that is carried on as the book grows)
+#            check_before (would this action be outside the slip?)
+# Writing:   prepare_slip + assemble_slip (the person, with a passkey),
+#            prepare_approval + assemble_approval (the person's yes to one action),
+#            write_stub (the agent), countersign, write_refusal, write_terms
+#            (the service), block_stamp_item (a proof from a public
+#            blockchain, to put beside a seal),
+#            prepare_cancellation + assemble_cancellation (the person ends a slip),
+#            write_acknowledgement (the agent's side says it was handed a cancellation),
+#            write_vouching, write_withdrawal (an organisation vouches for a name),
+#            write_pass (an agent hands part of its permission to a helper agent),
+#            write_book, make_show
+# Beside an agent: open_recorder (the stub writer: ask first, act, write
+#            the receipt), record_tools (an agent's tools behind the stub
+#            writer), arguments_fingerprint, NotTaken
+# Keys:      generate_key_set, key_set_from_seeds, key_set_seeds, thumbprint,
+#            key_set_fingerprint
+# Names:     the shared list of actions, the kinds of action, the rules of conduct
+
+from .actions import ACTION_KINDS, CONDUCT_RULES, RESERVED_PREFIX, SHARED_ACTIONS, action_kind
+from .approval import assemble_approval, prepare_approval
+from .blockstamp import block_fingerprint, block_stamp_item
+from .book import LIMITS, check_book, check_show, entry_line, make_show, open_checker, write_book
+from .compare import condition_words, limit_words, never_words
+from .encoding import Refusal, fingerprint, format_time, from_base64url, random_id, sha256, to_base64url, utf8
+from .guard import check_before
+from .headers import MIN_BLOCKS_AFTER, blocks_in_chain, check_header_chain
+from .keys import thumbprint
+from .pass_ import write_pass
+from .recorder import COUNTERSIGN_WITHIN_MS, Recorder, open_recorder
+from .seal import key_set_fingerprint
+from .service import REFUSAL_REASONS, write_refusal, write_terms
+from .signatures import generate_key_set, key_set_from_seeds, key_set_seeds, method_available
+from .slip import COVERABLE, assemble_slip, check_slip, prepare_slip
+from .standing import VOUCHED_KINDS, assemble_cancellation, prepare_cancellation, write_acknowledgement, write_vouching, write_withdrawal
+from .stub import countersign, write_stub
+from .tools import NotTaken, arguments_fingerprint, record_function, record_tools
+
+__all__ = [
+    'MIN_BLOCKS_AFTER', 'blocks_in_chain', 'check_header_chain',
+    'COUNTERSIGN_WITHIN_MS', 'NotTaken', 'Recorder', 'arguments_fingerprint', 'key_set_from_seeds', 'key_set_seeds', 'open_recorder',
+    'record_function', 'record_tools',
+    'ACTION_KINDS', 'CONDUCT_RULES', 'COVERABLE', 'LIMITS', 'REFUSAL_REASONS', 'RESERVED_PREFIX', 'SHARED_ACTIONS', 'VOUCHED_KINDS',
+    'Refusal', 'action_kind', 'assemble_approval', 'assemble_cancellation', 'assemble_slip', 'block_fingerprint', 'block_stamp_item',
+    'check_before', 'check_book', 'check_show', 'check_slip', 'condition_words', 'countersign', 'entry_line', 'fingerprint',
+    'format_time', 'from_base64url', 'generate_key_set', 'key_set_fingerprint', 'limit_words', 'make_show', 'method_available',
+    'never_words', 'open_checker', 'prepare_approval', 'prepare_cancellation', 'prepare_slip', 'random_id', 'sha256', 'thumbprint',
+    'to_base64url', 'utf8', 'write_acknowledgement', 'write_book', 'write_pass', 'write_refusal', 'write_stub', 'write_terms',
+    'write_vouching', 'write_withdrawal',
+]

provared/_js.py

@@ -0,0 +1,450 @@
+# How JavaScript reads and writes JSON and text, copied exactly, so that
+# this library gives the same answer as the JavaScript one for every input.
+#
+# JavaScript strings are counted, sorted and compared in UTF-16 code units,
+# and JSON.parse reads numbers as 64-bit floating-point values. Where Python
+# does otherwise, the functions here do as JavaScript does.
+
+import json
+import math
+import re
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+class _NotJson(ValueError):
+    pass
+
+
+def _no_constant(name):
+    # JSON.parse refuses NaN, Infinity and -Infinity, which Python's reader accepts.
+    raise _NotJson(name)
+
+
+def _number_int(text):
+    # JSON.parse gives -0 for "-0", and a floating-point value for a long
+    # number. Python gives 0 and an exact whole number.
+    if text == '-0':
+        return -0.0
+    if len(text) > 17:
+        return float(text)
+    number = int(text)
+    return number if abs(number) <= MAX_SAFE_INTEGER else float(text)
+
+
+def _number_float(text):
+    """A number written with a point or an exponent. JavaScript has one kind
+    of number, so one that is whole (and no larger than 2^53 - 1) is held
+    as a whole number, as it is written back in JavaScript. -0 stays -0."""
+    value = float(text)
+    if value.is_integer() and abs(value) <= MAX_SAFE_INTEGER and not (value == 0 and text.lstrip().startswith('-')):
+        return int(value)
+    return value
+
+
+def parse(text):
+    """JSON.parse: the value, with numbers as JavaScript reads them.
+
+    Raises ValueError where JSON.parse throws.
+    """
+    if not isinstance(text, str):
+        raise _NotJson('not text')
+    try:
+        return json.loads(text, parse_int=_number_int, parse_float=_number_float, parse_constant=_no_constant)
+    except RecursionError:
+        # Python's reader gives up on deep nesting, where JSON.parse does not.
+        return _parse_deep(text)
+    except (ValueError, OverflowError) as e:
+        raise _NotJson(str(e)) from None
+
+
+_WS = ' \t\n\r'
+_NUMBER = re.compile(r'-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?')
+_ESCAPES = {'"': '"', '\\': '\\', '/': '/', 'b': '\b', 'f': '\f', 'n': '\n', 'r': '\r', 't': '\t'}
+_HEX = re.compile(r'[0-9a-fA-F]{4}')
+
+
+def _parse_deep(text):
+    """JSON.parse without recursion, for deeply nested text."""
+    n = len(text)
+    i = 0
+
+    def skip(i):
+        while i < n and text[i] in _WS:
+            i += 1
+        return i
+
+    def read_string(i):
+        # text[i] is the opening quotation mark.
+        i += 1
+        out = []
+        start = i
+        while True:
+            if i >= n:
+                raise _NotJson('unterminated string')
+            c = text[i]
+            if c == '"':
+                out.append(text[start:i])
+                return ''.join(out).encode('utf-16-le', 'surrogatepass').decode('utf-16-le', 'surrogatepass'), i + 1
+            if c == '\\':
+                out.append(text[start:i])
+                if i + 1 >= n:
+                    raise _NotJson('bad escape')
+                e = text[i + 1]
+                if e == 'u':
+                    h = text[i + 2:i + 6]
+                    if not _HEX.fullmatch(h):
+                        raise _NotJson('bad escape')
+                    out.append(chr(int(h, 16)))
+                    i += 6
+                elif e in _ESCAPES:
+                    out.append(_ESCAPES[e])
+                    i += 2
+                else:
+                    raise _NotJson('bad escape')
+                start = i
+                continue
+            if ord(c) < 0x20:
+                raise _NotJson('control character in string')
+            i += 1
+
+    # A stack of containers being filled: [container, pending member name].
+    stack = []
+    root = None
+    have_root = False
+    i = skip(i)
+    while True:
+        if i >= n:
+            raise _NotJson('unexpected end')
+        c = text[i]
+        # Read one value, or open a container.
+        if c == '{' or c == '[':
+            container = {} if c == '{' else []
+            i = skip(i + 1)
+            if i < n and text[i] == ('}' if c == '{' else ']'):
+                value = container
+                i += 1
+            else:
+                if c == '{':
+                    if i >= n or text[i] != '"':
+                        raise _NotJson('expected a name')
+                    name, i = read_string(i)
+                    i = skip(i)
+                    if i >= n or text[i] != ':':
+                        raise _NotJson('expected a colon')
+                    i = skip(i + 1)
+                    stack.append([container, name])
+                else:
+                    stack.append([container, None])
+                continue
+        elif c == '"':
+            value, i = read_string(i)
+        elif c in '-0123456789':
+            m = _NUMBER.match(text, i)
+            if not m:
+                raise _NotJson('bad number')
+            t = m.group(0)
+            value = _number_int(t) if re.fullmatch(r'-?[0-9]+', t) else _number_float(t)
+            i = m.end()
+        elif text.startswith('true', i):
+            value, i = True, i + 4
+        elif text.startswith('false', i):
+            value, i = False, i + 5
+        elif text.startswith('null', i):
+            value, i = None, i + 4
+        else:
+            raise _NotJson('unexpected character')
+        # Put the value in place, and close what is complete.
+        while True:
+            if not stack:
+                root, have_root = value, True
+                break
+            container, name = stack[-1]
+            if isinstance(container, dict):
+                container[name] = value
+            else:
+                container.append(value)
+            i = skip(i)
+            if i < n and text[i] == ',':
+                i = skip(i + 1)
+                if isinstance(container, dict):
+                    if i >= n or text[i] != '"':
+                        raise _NotJson('expected a name')
+                    name, i = read_string(i)
+                    i = skip(i)
+                    if i >= n or text[i] != ':':
+                        raise _NotJson('expected a colon')
+                    i = skip(i + 1)
+                    stack[-1][1] = name
+                break
+            close = '}' if isinstance(container, dict) else ']'
+            if i < n and text[i] == close:
+                stack.pop()
+                value = container
+                i += 1
+                continue
+            raise _NotJson('expected a comma or the end of a container')
+        if have_root:
+            break
+        i = skip(i)
+    if skip(i) != n:
+        raise _NotJson('text after the value')
+    return root
+
+
+_STRING_ESCAPES = {'"': '\\"', '\\': '\\\\', '\b': '\\b', '\f': '\\f', '\n': '\\n', '\r': '\\r', '\t': '\\t'}
+
+
+def string(text):
+    """JSON.stringify of a string."""
+    out = ['"']
+    for c in text:
+        o = ord(c)
+        if c in _STRING_ESCAPES:
+            out.append(_STRING_ESCAPES[c])
+        elif o < 0x20 or 0xD800 <= o <= 0xDFFF:
+            out.append('\\u%04x' % o)
+        else:
+            out.append(c)
+    out.append('"')
+    return ''.join(out)
+
+
+def utf16_key(text):
+    """A key that sorts strings as JavaScript's default sort does: by UTF-16 code unit."""
+    return text.encode('utf-16-be', 'surrogatepass')
+
+
+def utf16_length(text):
+    """A string's "length" in JavaScript: its UTF-16 code units."""
+    if text.isascii():
+        return len(text)
+    return len(text.encode('utf-16-le', 'surrogatepass')) // 2
+
+
+def sort_strings(names):
+    return sorted(names, key=utf16_key)
+
+
+_INDEX = re.compile(r'0|[1-9][0-9]*')
+
+
+def keys(obj):
+    """Object.keys of an object read from JSON: names that are list indexes
+    (0 to 2**32 - 2) first, in number order, then the others as written."""
+    indexes = []
+    others = []
+    for k in obj:
+        if _INDEX.fullmatch(k) and int(k) <= 4294967294:
+            indexes.append(k)
+        else:
+            others.append(k)
+    if not indexes:
+        return others
+    indexes.sort(key=int)
+    return indexes + others
+
+
+def is_object(value):
+    """value !== null && typeof value === 'object' && !Array.isArray(value)"""
+    return isinstance(value, dict)
+
+
+def is_number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def is_safe_integer(value):
+    """Number.isSafeInteger"""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER
+    if isinstance(value, float):
+        return value == value and value not in (float('inf'), float('-inf')) and value.is_integer() and abs(value) <= MAX_SAFE_INTEGER
+    return False
+
+
+def whole(value):
+    """A number that JavaScript holds as a whole number, as an int: so 2.0 is 2.
+    Anything else is given back as it is."""
+    if isinstance(value, float) and value.is_integer() and abs(value) <= MAX_SAFE_INTEGER:
+        return int(value)
+    return value
+
+
+def in_key_order(obj):
+    """An object with its members in the order Object.keys gives them."""
+    return {k: obj[k] for k in keys(obj)}
+
+
+def property_key(name):
+    """The name of a member as JavaScript holds it: always text. A dict key that
+    is a number, True, False or None becomes the text JavaScript would give
+    it; any other key is not plain data (TypeError)."""
+    if isinstance(name, str):
+        return name
+    if name is None:
+        return 'null'
+    if isinstance(name, bool):
+        return 'true' if name else 'false'
+    if is_number(name):
+        return number_string(name)
+    raise TypeError('not plain data')
+
+
+def finite(value):
+    """Number.isFinite, for a Python number: a whole number too large for a
+    floating-point number is Infinity in JavaScript."""
+    if not is_number(value):
+        return False
+    try:
+        return math.isfinite(value)
+    except OverflowError:
+        return False
+
+
+def truthy(value):
+    """Whether JavaScript counts a value as true: everything but undefined,
+    null, false, 0, NaN and the empty text. An empty list or object counts."""
+    if value is None or value is False:
+        return False
+    if is_number(value):
+        return value == value and value != 0
+    if isinstance(value, str):
+        return value != ''
+    return True
+
+
+def strict_equal(a, b):
+    """a === b for values read from JSON: true and 1 are not the same, nor are
+    a number and a text."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if is_number(a) and is_number(b):
+        return a == b
+    if a is None or b is None:
+        return a is b
+    if isinstance(a, str) and isinstance(b, str):
+        return a == b
+    return a is b
+
+
+def includes(items, value):
+    """Array.prototype.includes, which compares as === does (and finds NaN)."""
+    if isinstance(value, float) and value != value:
+        return any(isinstance(x, float) and x != x for x in items)
+    return any(strict_equal(x, value) for x in items)
+
+
+class IdentityMap:
+    """A JavaScript Map whose keys are objects: found by identity, not by value."""
+
+    __slots__ = ('_items',)
+
+    def __init__(self, items=None):
+        self._items = dict(items._items) if isinstance(items, IdentityMap) else {}
+
+    def get(self, key, default=None):
+        found = self._items.get(id(key))
+        return default if found is None else found[1]
+
+    def set(self, key, value):
+        self._items[id(key)] = (key, value)
+
+    def has(self, key):
+        return id(key) in self._items
+
+    def values(self):
+        return [v for _, v in self._items.values()]
+
+    def __len__(self):
+        return len(self._items)
+
+
+def number_text(value):
+    """String(value) for a whole number."""
+    if isinstance(value, float):
+        return str(int(value))
+    return str(value)
+
+
+def number_value(value):
+    """The number JavaScript would hold for a Python number: a float, or an
+    int that a float holds exactly. A whole number beyond 2^53 - 1 becomes
+    the nearest float, as JSON.parse would read it. Raises OverflowError for
+    a whole number too large for a float. A number of a class built on int
+    or float (an Enum of whole numbers, say) is taken as its plain value."""
+    if isinstance(value, int) and not isinstance(value, bool):
+        value = int.__int__(value)
+        if -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
+            return value
+        return float(value)
+    if isinstance(value, float):
+        return float.__float__(value)
+    return value
+
+
+def number_string(value):
+    """Number.prototype.toString() in base 10, which JSON.stringify also
+    uses for a finite number: the fewest digits that read back as the same
+    number, written as ECMAScript sets out (section 6.1.6.1.20). So 1e21 is
+    "1e+21", 1.5e-7 is "1.5e-7", 1e-6 is "0.000001" and 0.1 + 0.2 is
+    "0.30000000000000004". Raises OverflowError for a whole number too large
+    for a float."""
+    value = number_value(value)
+    if isinstance(value, int):
+        return str(value)
+    if value != value:
+        return 'NaN'
+    if value in (float('inf'), float('-inf')):
+        return 'Infinity' if value > 0 else '-Infinity'
+    if value == 0:
+        # Both 0 and -0 are written "0".
+        return '0'
+    sign = '-' if value < 0 else ''
+    # Python's repr gives the same fewest digits, closest to the value.
+    mantissa, _, exponent = repr(abs(value)).partition('e')
+    whole, _, fraction = mantissa.partition('.')
+    digits = whole + fraction
+    # The value is 0.digits times 10 to the power "point".
+    point = len(whole) + (int(exponent) if exponent else 0)
+    stripped = digits.lstrip('0')
+    point -= len(digits) - len(stripped)
+    digits = stripped.rstrip('0')
+    k = len(digits)
+    n = point
+    if k <= n <= 21:
+        out = digits + '0' * (n - k)
+    elif 0 < n <= 21:
+        out = digits[:n] + '.' + digits[n:]
+    elif -6 < n <= 0:
+        out = '0.' + '0' * (-n) + digits
+    else:
+        e = n - 1
+        mark = '+' if e >= 0 else '-'
+        out = (digits if k == 1 else digits[0] + '.' + digits[1:]) + 'e' + mark + str(abs(e))
+    return sign + out
+
+
+def stringify(value):
+    """JSON.stringify for plain data (objects, lists, text, numbers, true,
+    false and null): NaN and the infinities are written null, -0 as 0, and
+    members in the order Object.keys gives them."""
+    if value is None:
+        return 'null'
+    if value is True:
+        return 'true'
+    if value is False:
+        return 'false'
+    if isinstance(value, str):
+        return string(value)
+    if is_number(value):
+        if isinstance(value, float) and (value != value or value in (float('inf'), float('-inf'))):
+            return 'null'
+        return number_string(value)
+    if isinstance(value, list):
+        return '[' + ','.join(stringify(v) for v in value) + ']'
+    if isinstance(value, dict):
+        return '{' + ','.join(string(k) + ':' + stringify(value[k]) for k in keys(value)) + '}'
+    raise TypeError('not plain data')

provared/actions.py

@@ -0,0 +1,84 @@
+# The shared list of action names, the kinds of action, and the rules of
+# conduct a slip can state. Format description, section 16.
+#
+# This is a first draft, written before real agents have used it. Anyone may
+# go on using action names of their own; names that begin "provared." are
+# reserved for this list.
+
+RESERVED_PREFIX = 'provared.'
+"""Every action name that begins with this is reserved for the shared list."""
+
+ACTION_KINDS = {
+    'reads': 'Looks at data without changing it.',
+    'changes': 'Creates or changes data in a way that can be put back.',
+    'destroys': 'Removes data or a resource in a way that may not be put back.',
+    'sends': 'Sends a message or data to a person, to the public or to another system.',
+    'commits': 'Binds the person to something: an order, a booking, an agreement, an account.',
+    'grants': 'Gives someone or something access or permission.',
+    'runs': 'Runs a program or a command.',
+    'enters': 'Signs in to a system or an account.',
+}
+"""The kinds of action. Each shared action belongs to exactly one."""
+
+SHARED_ACTIONS = {
+    'provared.data.read': ('reads', 'Read stored data or a file.'),
+    'provared.data.search': ('reads', 'Search stored data.'),
+    'provared.data.create': ('changes', 'Create a new item of data or a new file.'),
+    'provared.data.change': ('changes', 'Change an item of data or a file that exists.'),
+    'provared.data.delete': ('destroys', 'Delete data or a file.'),
+    'provared.data.export': ('sends', 'Copy data out of the system that keeps it.'),
+    'provared.message.read': ('reads', 'Read messages.'),
+    'provared.message.draft': ('changes', 'Write a message without sending it.'),
+    'provared.message.send': ('sends', 'Send a message to a person.'),
+    'provared.post.publish': ('sends', 'Publish something where the public can see it.'),
+    'provared.calendar.read': ('reads', 'Read a calendar.'),
+    'provared.calendar.change': ('changes', 'Add, move or remove an entry in a calendar.'),
+    'provared.booking.make': ('commits', 'Book a place, a time or a service.'),
+    'provared.booking.cancel': ('commits', 'Cancel a booking.'),
+    'provared.order.place': ('commits', 'Place an order for goods or services.'),
+    'provared.order.cancel': ('commits', 'Cancel an order.'),
+    'provared.terms.accept': ('commits', 'Accept terms, or sign an agreement.'),
+    'provared.form.submit': ('commits', 'Submit a form or an application.'),
+    'provared.account.create': ('commits', 'Open an account.'),
+    'provared.account.sign-in': ('enters', 'Sign in to an account or a system.'),
+    'provared.access.grant': ('grants', 'Give a person or a program access.'),
+    'provared.access.remove': ('changes', 'Take access away from a person or a program.'),
+    'provared.key.create': ('grants', 'Make a key or a password that gives access.'),
+    'provared.code.read': ('reads', 'Read the source of a program.'),
+    'provared.code.change': ('changes', 'Change the source of a program.'),
+    'provared.code.run': ('runs', 'Run a program or a command.'),
+    'provared.code.release': ('runs', 'Put a program into live use.'),
+    'provared.system.configure': ('changes', 'Change the settings of a system.'),
+    'provared.web.read': ('reads', 'Read a public web page.'),
+    'provared.agent.instruct': ('sends', 'Hand a task to another agent.'),
+}
+"""The shared actions: name, kind, and what the name means."""
+
+CONDUCT_RULES = {
+    'impersonate': 'Never claim to be a human being, or to be anyone other than the agent of the person who signed the slip.',
+    'bypass': 'Never go around an access control, a block or a refusal.',
+    'escalate': 'Never obtain or use access that it was not given.',
+    'conceal': 'Never hide, alter or leave out its own records.',
+    'deceive': 'Never state what it has reason to believe is false, and never make up a record or a result.',
+    'harass': 'Never threaten, pressure or attack a person.',
+    'disclose': 'Never pass information that is not public to anyone the slip does not name.',
+    'continue-after-stop': 'Never carry on after being told to stop.',
+}
+"""The rules of conduct a slip can state. They are the person's signed
+instruction. No check of a record can show that an agent kept them."""
+
+
+def action_kind(name):
+    """The kind of a shared action, or None for a name that is not on the shared
+    list (a name of the writer's own)."""
+    return SHARED_ACTIONS[name][0] if isinstance(name, str) and name in SHARED_ACTIONS else None
+
+
+def is_never_name(name):
+    """Whether a name may stand in a "never" list: a kind of action, or a rule of conduct."""
+    return isinstance(name, str) and (name in ACTION_KINDS or name in CONDUCT_RULES)
+
+
+def is_unknown_reserved(name):
+    """Whether an action name is reserved and not on the shared list."""
+    return isinstance(name, str) and name.startswith(RESERVED_PREFIX) and name not in SHARED_ACTIONS