provared 0.3.0__tar.gz → 0.4.0__tar.gz

{provared-0.3.0/src/provared.egg-info → provared-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provared
-Version: 0.3.0
+Version: 0.4.0
 Summary: Proof of what an AI agent was allowed to do, and what it then did. A passkey-signed permission with limits a machine can check, a signed receipt for each action, and a checker. Evidence, not a verdict.
 Author: Pavel Izmaylov
 License-Expression: Apache-2.0 AND CC-BY-4.0
@@ -19,7 +19,7 @@ License-File: LICENSE-CC-BY-4.0.txt
 Requires-Dist: cryptography>=48
 Dynamic: license-file
 
-# Provared for Python
+# <img src="https://prova.red/favicon.svg" alt="" width="36"> Provared for Python
 
 Proof of what an AI agent was allowed to do, and what it then did.
 
@@ -34,7 +34,7 @@ particular to Python.
 
 ## Status
 
-**Version 0.3.0, a draft**, the same version as the JavaScript library.
+**Version 0.4.0, a draft**, the same version as the JavaScript library.
 Published as it is, by one author in their own time; fixes as time
 allows. It gives the same answer, case for case, as the shared test
 files in [`test-vectors/`](https://github.com/provared/provared/tree/main/test-vectors) show: the same result, the
@@ -46,7 +46,10 @@ needs, `cryptography`, does not yet have SLH-DSA (FIPS 205), the method
 of a seal's third signature. So a seal's third signature is reported as
 "not checked on this device", and never as a pass, as the checking page
 in a browser reports it. Seals are checked in full by the JavaScript
-command-line checker.
+command-line checker. The check before acting, and so the stub writer,
+goes on after a seal whose Ed25519 and ML-DSA-87 signatures were checked
+here, and its answer says what was not checked (`notChecked`); any
+other signature left unchecked still allows nothing.
 
 ## Install
 

{provared-0.3.0 → provared-0.4.0}/README.md

@@ -1,4 +1,4 @@
-# Provared for Python
+# <img src="https://prova.red/favicon.svg" alt="" width="36"> Provared for Python
 
 Proof of what an AI agent was allowed to do, and what it then did.
 
@@ -13,7 +13,7 @@ particular to Python.
 
 ## Status
 
-**Version 0.3.0, a draft**, the same version as the JavaScript library.
+**Version 0.4.0, a draft**, the same version as the JavaScript library.
 Published as it is, by one author in their own time; fixes as time
 allows. It gives the same answer, case for case, as the shared test
 files in [`test-vectors/`](https://github.com/provared/provared/tree/main/test-vectors) show: the same result, the
@@ -25,7 +25,10 @@ needs, `cryptography`, does not yet have SLH-DSA (FIPS 205), the method
 of a seal's third signature. So a seal's third signature is reported as
 "not checked on this device", and never as a pass, as the checking page
 in a browser reports it. Seals are checked in full by the JavaScript
-command-line checker.
+command-line checker. The check before acting, and so the stub writer,
+goes on after a seal whose Ed25519 and ML-DSA-87 signatures were checked
+here, and its answer says what was not checked (`notChecked`); any
+other signature left unchecked still allows nothing.
 
 ## Install
 

{provared-0.3.0 → provared-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "provared"
-version = "0.3.0"
+version = "0.4.0"
 description = "Proof of what an AI agent was allowed to do, and what it then did. A passkey-signed permission with limits a machine can check, a signed receipt for each action, and a checker. Evidence, not a verdict."
 keywords = ["ai-agent", "agent", "audit-trail", "permission", "authorization", "receipt", "tamper-evident", "passkey", "webauthn", "jws", "ed25519", "ml-dsa", "post-quantum", "evidence", "langchain"]
 readme = "README.md"

{provared-0.3.0 → provared-0.4.0}/src/provared/encoding.py

@@ -250,7 +250,7 @@ def format_time(when):
     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:
+    if isinstance(when, _datetime.datetime) and when.utcoffset() 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')

{provared-0.3.0 → provared-0.4.0}/src/provared/guard.py

@@ -7,8 +7,10 @@
 # a period which a stub dated after it already overfills. It writes
 # nothing and changes nothing.
 
+import datetime
 from collections.abc import Mapping
 
+from . import _js
 from . import fields as f
 from .book import MAX_ENTRIES, MAX_LINE_BYTES, _Ids, check_approval_record, check_book_keeping_state, fixed_options, keys_of, pass_as_slip
 from .compare import compare_with_slip
@@ -53,9 +55,11 @@ def check_before(book, proposal, options=None, **named):
     the passkeys this check trusts) must be given: a slip signed by any
     other key allows nothing.
 
-    Returns {"allowed", "problems", "breaches", "needs"}. "allowed" is True
-    only if the record so far is sound, this device checked every signature
-    in it, and the action would be inside the slip. "needs" lists what the
+    Returns {"allowed", "problems", "breaches", "needs"}, and "notChecked"
+    where it applies. "allowed" is True only if the record so far is sound,
+    this device checked every signature in it (or every one but the third
+    signature of a seal whose first two it checked, which "notChecked" then
+    names), and the action would be inside the slip. "needs" lists what the
     slip asks to go with the action. A needed approval must be handed over,
     or the action is not allowed. A needed countersignature cannot be known
     beforehand: the action is allowed, and is inside the slip only if the
@@ -73,6 +77,78 @@ def check_before_read(read, proposal, options=None):
     return _decide(read, proposal, options)
 
 
+SEAL_THIRD = 'SLH-DSA-SHA2-256s'
+
+
+def _only_seal_third_unchecked(result):
+    """The methods not checked on this device, if the only thing not checked
+    is the third signature of one or more seals whose Ed25519 and ML-DSA-87
+    signatures were checked here; otherwise None. It counts as the checker
+    counts for "fully checked" (book.py): a signature whose method is not
+    built in, or an entry with nothing to check, is not checked; a time-stamp
+    from a service the reader did not name is not "unchecked", it is uncounted."""
+    if result['summary']['fullyChecked']:
+        return None
+    state = {'skipped': False, 'excused': 0}
+    missing = set()
+
+    def note(items):
+        if len(items) == 0:
+            state['skipped'] = True
+        for x in items:
+            if x.get('state') == 'unavailable':
+                missing.add(x.get('method'))
+
+    def stamps(items):
+        for x in items:
+            if x.get('state') == 'unavailable':
+                missing.add('stamp')
+
+    for e in result['entries']:
+        kind = e.get('kind')
+        if kind == 'seal':
+            sigs = e.get('signatures') or []
+            by = {x.get('method'): x.get('state') for x in sigs}
+            third = len(sigs) == 3 and by.get('Ed25519') == 'valid' and by.get('ML-DSA-87') == 'valid' and by.get(SEAL_THIRD) == 'unavailable'
+            if third:
+                state['excused'] += 1
+            else:
+                note(sigs)
+            stamps(e.get('stamps') or [])
+        elif kind == 'slip':
+            sig = e.get('signature')
+            if not sig or sig.get('state') == 'unavailable':
+                missing.add(sig.get('alg') if sig else 'passkey')
+            elif sig.get('state') == 'unchecked':
+                state['skipped'] = True
+        elif kind == 'stub':
+            note(e.get('signatures') or [])
+            counter = e.get('countersignature') or {'state': 'absent', 'signatures': []}
+            if counter.get('state') != 'absent':
+                note(counter.get('signatures') or [])
+            approval = e.get('approval') or {'state': 'absent'}
+            if approval.get('state') == 'unavailable':
+                missing.add(approval.get('alg'))
+        elif kind == 'cancellation':
+            sig = e.get('signature')
+            if not sig:
+                state['skipped'] = True
+            elif sig.get('state') == 'unavailable':
+                missing.add(sig.get('alg'))
+            stamps(e.get('stamps') or [])
+        elif kind in ('refusal', 'terms', 'vouching', 'withdrawal', 'pass', 'acknowledgement'):
+            note(e.get('signatures') or [])
+        else:
+            state['skipped'] = True
+    for h in result.get('held') or []:
+        stamps(h.get('stamps') or [])
+        for a in h.get('acknowledgements') or []:
+            note(a.get('signatures') or [])
+    if not state['skipped'] and len(missing) == 0 and state['excused'] > 0:
+        return [SEAL_THIRD]
+    return None
+
+
 def _decide(read, proposal, options):
     answer = {'allowed': False, 'problems': [], 'breaches': [], 'needs': []}
     try:
@@ -85,17 +161,35 @@ def _decide(read, proposal, options):
         result, state, beside = got['result'], got['state'], got['beside']
         if result['summary']['problemFound']:
             raise _not_sound('A problem was found in the record so far. It must be looked at before the agent acts again.')
-        # A record this device could only partly check is not a pass, here either.
-        if not result['summary']['fullyChecked']:
+        # A record this device could only partly check is not a pass, here
+        # either, with one stated exception: a seal's third signature
+        # (SLH-DSA), where its first two were checked here. A seal widens no
+        # permission, and this version cannot check that method (F-79), so it
+        # would otherwise be refused everything once the book holds a seal.
+        # The answer names what was not checked.
+        not_checked = _only_seal_third_unchecked(result)
+        if not result['summary']['fullyChecked'] and not_checked is None:
             raise _not_sound('This device could not check every signature in the record so far.')
+        if not_checked is not None:
+            answer['notChecked'] = not_checked
         if not all(e.get('compared') is True for e in result['entries'] if e['kind'] in ('stub', 'pass')):
             raise _not_sound('This device could not compare every stub and every pass in the record so far with its slip.')
         if result['size'] >= MAX_ENTRIES:
             raise Refusal('too-large', 'The book is full: it holds 100,000 entries.')
 
         f.members(proposal, ['action', 'slip'], ['amount', 'approval', 'details', 'pass', 'terms', 'when', 'with'], 'proposal')
+        # The time, as the stub writer takes it: a number of milliseconds or a
+        # datetime with a time zone. Text is read by rules that differ between
+        # devices.
         when_given = proposal.get('when')
-        c = {'action': proposal['action'], 'when': format_time(now_ms() if when_given is None else when_given)}
+        given = now_ms() if when_given is None else when_given
+        if not _js.is_number(given) and not (isinstance(given, datetime.datetime) and given.utcoffset() is not None):
+            raise Refusal('bad-field', 'when: must be a number of milliseconds, or a Date.')
+        try:
+            when_text = format_time(given)
+        except ValueError:
+            raise Refusal('bad-field', 'when: does not give a time.') from None
+        c = {'action': proposal['action'], 'when': when_text}
         for name in ('amount', 'details', 'with'):
             if name in proposal:
                 c[name] = proposal[name]

{provared-0.3.0 → provared-0.4.0}/src/provared/recorder.py

@@ -322,7 +322,7 @@ def _time_value(value):
     library."""
     if _js.is_number(value):
         return _time_clip(value)
-    if isinstance(value, datetime.datetime) and value.tzinfo is not None:
+    if isinstance(value, datetime.datetime) and value.utcoffset() is not None:
         epoch = datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc)
         return _time_clip((value - epoch) // datetime.timedelta(milliseconds=1))
     raise Refusal('bad-field', 'when: must be a number of milliseconds, or a Date.')
@@ -1028,6 +1028,9 @@ class Recorder:
         def work(call):
             self._write_waiting(self._now())
             when = call['when'] if call['when'] is not _ABSENT else self._now()
+            # In the words of the check before acting, which "act" and "before" give.
+            if not _js.finite(when):
+                raise Refusal('bad-field', 'when: does not give a time.')
             if self._ahead_of_clock(when):
                 raise _not_written('The stub was not written: it is dated ahead of the clock.')
             made = self._compose_stub(call, when)

{provared-0.3.0 → provared-0.4.0}/src/provared/signatures.py

@@ -29,6 +29,10 @@ except ImportError:  # "cryptography" before version 48
 
 SLH = 'SLH-DSA-SHA2-256s'
 
+# The length of a signature, in bytes, by method (RFC 8032, FIPS 204,
+# FIPS 205).
+_SIGNATURE_BYTES = {'Ed25519': 64, 'ML-DSA-87': 4627, SLH: 29792}
+
 
 def method_available(alg):
     """Whether this device can check signatures made with this method."""
@@ -66,6 +70,10 @@ def verify_signature(jwk, signature, data, without=()):
     without them; it can only withhold a pass.
     """
     alg = jwk['alg']
+    # A signature of another length than its method's can never check, so it
+    # is refused on every device, whether or not this one has the method.
+    if alg in _SIGNATURE_BYTES and len(signature) != _SIGNATURE_BYTES[alg]:
+        return 'invalid'
     if alg == SLH:
         return 'unavailable'
     if alg not in ('Ed25519', 'ML-DSA-87', 'ES256', 'RS256'):

{provared-0.3.0 → provared-0.4.0/src/provared.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provared
-Version: 0.3.0
+Version: 0.4.0
 Summary: Proof of what an AI agent was allowed to do, and what it then did. A passkey-signed permission with limits a machine can check, a signed receipt for each action, and a checker. Evidence, not a verdict.
 Author: Pavel Izmaylov
 License-Expression: Apache-2.0 AND CC-BY-4.0
@@ -19,7 +19,7 @@ License-File: LICENSE-CC-BY-4.0.txt
 Requires-Dist: cryptography>=48
 Dynamic: license-file
 
-# Provared for Python
+# <img src="https://prova.red/favicon.svg" alt="" width="36"> Provared for Python
 
 Proof of what an AI agent was allowed to do, and what it then did.
 
@@ -34,7 +34,7 @@ particular to Python.
 
 ## Status
 
-**Version 0.3.0, a draft**, the same version as the JavaScript library.
+**Version 0.4.0, a draft**, the same version as the JavaScript library.
 Published as it is, by one author in their own time; fixes as time
 allows. It gives the same answer, case for case, as the shared test
 files in [`test-vectors/`](https://github.com/provared/provared/tree/main/test-vectors) show: the same result, the
@@ -46,7 +46,10 @@ needs, `cryptography`, does not yet have SLH-DSA (FIPS 205), the method
 of a seal's third signature. So a seal's third signature is reported as
 "not checked on this device", and never as a pass, as the checking page
 in a browser reports it. Seals are checked in full by the JavaScript
-command-line checker.
+command-line checker. The check before acting, and so the stub writer,
+goes on after a seal whose Ed25519 and ML-DSA-87 signatures were checked
+here, and its answer says what was not checked (`notChecked`); any
+other signature left unchecked still allows nothing.
 
 ## Install
 

{provared-0.3.0 → provared-0.4.0}/src/provared.egg-info/SOURCES.txt

@@ -36,10 +36,12 @@ src/provared.egg-info/SOURCES.txt
 src/provared.egg-info/dependency_links.txt
 src/provared.egg-info/requires.txt
 src/provared.egg-info/top_level.txt
+tests/test_check_before.py
 tests/test_dev.py
 tests/test_record_function.py
 tests/test_recorder.py
 tests/test_records.py
 tests/test_review2.py
+tests/test_signatures.py
 tests/test_tree.py
 tests/test_vectors.py

provared-0.4.0/tests/test_check_before.py

@@ -0,0 +1,44 @@
+# The check before acting, with a seal in the book (format description,
+# section 20). This version cannot check a seal's third signature
+# (SLH-DSA-SHA2-256s), so the check goes on where the seal's first two
+# signatures were checked here, and says what it did not check. A book of a
+# permission and a seal alone shows the rule itself: the seal's first two
+# signatures are the only ones of their methods. Python cannot make a seal,
+# so the book is the one in the shared test file, made by the JavaScript
+# library.
+
+import json
+import pathlib
+import unittest
+
+from provared import check_before
+
+VECTORS = pathlib.Path(__file__).resolve().parents[2] / 'test-vectors'
+SLH = 'SLH-DSA-SHA2-256s'
+NOT_CHECKED = [{'code': 'record-not-sound', 'message': 'This device could not check every signature in the record so far.'}]
+
+
+def shared_case(name):
+    cases = json.loads((VECTORS / 'check-before.json').read_text(encoding='utf-8'))['cases']
+    return next(c for c in cases if c['name'] == name)
+
+
+class TheSealRule(unittest.TestCase):
+    def test_the_third_signature_is_let_through_only_where_the_first_two_were_both_checked_here(self):
+        c = shared_case('a permission and a seal, on a device without Ed25519 either')
+        trusted = {'issuerKeys': c['options']['issuerKeys'], 'sealKeys': c['options']['sealKeys']}
+        lone = c['text']
+        self.assertEqual([json.loads(line).keys() >= {'seal'} for line in lone.splitlines()], [False, True], 'a permission and a seal')
+        for without in ([], [SLH]):
+            r = check_before(lone, c['proposal'], {**trusted, 'withoutMethods': without})
+            self.assertTrue(r['allowed'], without)
+            self.assertEqual(r['notChecked'], [SLH])
+        for also in ('ML-DSA-87', 'Ed25519'):
+            r = check_before(lone, c['proposal'], {**trusted, 'withoutMethods': [SLH, also]})
+            self.assertFalse(r['allowed'], f'without {also} as well: refused')
+            self.assertEqual(r['problems'], NOT_CHECKED)
+            self.assertNotIn('notChecked', r)
+
+
+if __name__ == '__main__':
+    unittest.main()

{provared-0.3.0 → provared-0.4.0}/tests/test_recorder.py

@@ -22,6 +22,7 @@ from provared import (
     Recorder,
     Refusal,
     arguments_fingerprint,
+    check_before,
     check_book,
     countersign,
     fingerprint,
@@ -285,6 +286,50 @@ class PythonValues(unittest.TestCase):
         self.assertTrue(r['done'])
         self.assertEqual(check_book(writer.book())['entries'][1]['content']['when'], '2026-10-05T10:00:00Z')
 
+    def test_a_datetime_whose_time_zone_gives_no_offset_is_refused_in_plain_words(self):
+        # Python's own rule: a datetime is "aware" only where its time zone
+        # gives an offset. One that gives none is read as local time, which
+        # differs from one device to another: the check before acting and
+        # the writer refuse it in the same words, and nothing is written.
+        class NoOffset(datetime.tzinfo):
+            def utcoffset(self, dt):
+                return None
+
+            def dst(self, dt):
+                return None
+
+        moment = datetime.datetime(2026, 10, 5, 10, 0, tzinfo=NoOffset())
+        refusal = {'code': 'bad-field', 'message': 'when: must be a number of milliseconds, or a Date.'}
+        w = World()
+        answer = check_before(w.book(), {'slip': w.slip_fingerprint, **order(1), 'when': moment}, issuer_keys=w.issuer_keys)
+        self.assertFalse(answer['allowed'])
+        self.assertEqual(answer['problems'], [refusal])
+        with self.assertRaises(Refusal) as refused:
+            _time_value(moment)
+        self.assertEqual((refused.exception.code, refused.exception.message), (refusal['code'], refusal['message']))
+        writer = w.open()
+        for call in (lambda more: writer.before(order(1), more), lambda more: writer.act(order(1), lambda: None, more), lambda more: writer.record(order(1), more)):
+            with self.assertRaises(Refusal) as refused:
+                call({'when': moment})
+            self.assertEqual((refused.exception.code, refused.exception.message), (refusal['code'], refusal['message']))
+        self.assertEqual(writer.book(), w.book())
+
+    def test_a_time_that_gives_no_time_is_refused_in_plain_words_by_record_too(self):
+        # "before" and "act" answer as the check before acting does;
+        # "record", which does not ask first, refuses in the same words.
+        plainly = {'code': 'bad-field', 'message': 'when: does not give a time.'}
+        w = World()
+        writer = w.open()
+        for when in (float('nan'), float('inf'), 9e15):
+            self.assertEqual(writer.before(order(1), {'when': when})['problems'], [plainly])
+            acted = writer.act(order(1), lambda: self.fail('the action was taken'), {'when': when})
+            self.assertFalse(acted['done'])
+            self.assertEqual(acted['answer']['problems'], [plainly])
+            with self.assertRaises(Refusal) as refused:
+                writer.record(order(1), {'when': when})
+            self.assertEqual((refused.exception.code, refused.exception.message), (plainly['code'], plainly['message']))
+        self.assertEqual(writer.book(), w.book())
+
     def test_what_is_not_plain_data_is_refused_where_javascript_could_not_copy_it(self):
         w = World()
         writer = w.open()

provared-0.4.0/tests/test_signatures.py

@@ -0,0 +1,47 @@
+# The length of a signature. An Ed25519 signature is 64 bytes, an ML-DSA-87
+# signature 4,627 and an SLH-DSA-SHA2-256s signature 29,792 (RFC 8032,
+# FIPS 204, FIPS 205). One shorter or longer can never check, so no device
+# calls it "not checked here", whether or not it has the method (format
+# description, section 3.9). The shared test files hold a seal whose third
+# signature is cut short; these tests hold the rule for every method, both
+# ways, with and without the method.
+
+import json
+import unittest
+
+from test_recorder import World, order
+
+from provared import check_book, to_base64url, write_book
+from provared.signatures import generate_key_set, verify_signature
+
+SLH_KEY = {'alg': 'SLH-DSA-SHA2-256s', 'kty': 'AKP', 'pub': to_base64url(bytes(64))}
+
+
+class SignatureLengths(unittest.TestCase):
+    def test_a_signature_of_another_length_than_its_methods_is_invalid_with_the_method_or_without_it(self):
+        keys, _ = generate_key_set()
+        for key, length in ((keys[0], 64), (keys[1], 4627), (SLH_KEY, 29792)):
+            for wrong in (0, length - 1, length + 1, 2 * length):
+                for without in ((), (key['alg'],)):
+                    where = f"{key['alg']}, {wrong} bytes, {'without' if without else 'with'} the method"
+                    self.assertEqual(verify_signature(key, bytes(wrong), b'x', without), 'invalid', where)
+            # Of the right length, on a device without the method: not checked here, never a pass.
+            self.assertEqual(verify_signature(key, bytes(length), b'x', (key['alg'],)), 'unavailable', key['alg'])
+
+    def test_a_book_whose_signatures_are_emptied_has_a_problem_on_a_device_with_neither_method(self):
+        w = World()
+        writer = w.open()
+        self.assertTrue(writer.act(order(1), lambda: None)['done'])
+        entries = [{'slip': w.slip}]
+        for line in writer.book().splitlines()[1:]:
+            entry = json.loads(line)
+            entry['stub'] = {**entry['stub'], 'signatures': [{**s, 'signature': ''} for s in entry['stub']['signatures']]}
+            entries.append(entry)
+        result = check_book(write_book(entries), {'issuerKeys': w.issuer_keys, 'withoutMethods': ['Ed25519', 'ML-DSA-87']})
+        self.assertTrue(result['summary']['problemFound'])
+        self.assertFalse(result['summary']['intact'])
+        self.assertEqual([s['state'] for s in result['entries'][1]['signatures']], ['invalid', 'invalid'])
+
+
+if __name__ == '__main__':
+    unittest.main()