dethron 0.1.0__py3-none-any.whl

dethron/__init__.py

@@ -0,0 +1,28 @@
+"""Verifiable message delivery over Reticulum and LXMF.
+
+Guaranteed delivery is impossible over intermittent contact: if the recipient never
+appears, nothing reaches them. What is possible is knowing, with cryptographic proof and
+without trusting the relay, which state a message is in — it entered the network, it is
+pending at a named relay, or the recipient signed for it.
+
+    from dethron import Node
+
+    with Node('./alice', peers=['relay.example:45810']) as node:
+        handoff = node.send(payload, to=recipient, via=relay_propagation)
+        proof = node.custody_of(handoff['transient_id'], relay=relay_contact)
+
+`proof` is the relay's signature over the message it is holding, for that recipient. It
+proves entry, not delivery: only the recipient's receipt proves exit, and a relay that
+attests and then discards is named by the absence of that receipt.
+"""
+from . import custody
+from .audit import verify_directory
+from .endpoint import Endpoint
+from .node import Node, parse_contact, parse_relay
+from .protocol import data_envelope, decode, encode, receipt_envelope
+from .wire import authenticate, declared_expiry
+
+__version__ = '0.1.0'
+__all__ = ['Endpoint', 'Node', 'authenticate', 'custody', 'data_envelope', 'decode',
+           'declared_expiry', 'encode', 'parse_contact', 'parse_relay', 'receipt_envelope',
+           'verify_directory']

dethron/adapter.py

@@ -0,0 +1,75 @@
+"""LXMF direct delivery adapter. pump() is explicit; no simulated network fallback."""
+import threading
+import time
+
+import LXMF
+import RNS
+
+from .protocol import APPLICATION, encode
+from .wire import authenticate
+
+
+class Adapter:
+    def __init__(self, router, source, mailbox, emit):
+        self.router, self.source, self.mailbox, self.emit = router, source, mailbox, emit
+        self.active = set()
+        self.lock = threading.RLock()
+        router.register_delivery_callback(self.receive)
+
+    def receive(self, message):
+        try:
+            identity = RNS.Identity.recall(message.source_hash)
+            if identity is None:
+                raise ValueError("unknown source identity")
+            obj = authenticate(message.packed, identity.get_public_key(), self.source.hash.hex(), time.time())
+            fresh = self.mailbox.accept_verified(obj, message.packed, time.time())
+            self.emit("confirmed" if obj["kind"] == "receipt" else "received",
+                      id=obj["id"], fresh=fresh, digest=obj["digest"])
+        except Exception as exc:
+            self.emit("rejected", error=repr(exc))
+
+    def transmit(self, destination, body, callback=None, failed=None):
+        dest_hash = bytes.fromhex(destination)
+        identity = RNS.Identity.recall(dest_hash)
+        if identity is None:
+            RNS.Transport.request_path(dest_hash)
+            return False
+        target = RNS.Destination(identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "lxmf", "delivery")
+        message = LXMF.LXMessage(target, self.source, body, APPLICATION, desired_method=LXMF.LXMessage.DIRECT)
+        if callback:
+            message.register_delivery_callback(callback)
+        if failed:
+            message.register_failed_callback(failed)
+        self.router.handle_outbound(message)
+        return True
+
+    def _complete(self, key, message_id, succeeded):
+        with self.lock:
+            if succeeded:
+                self.mailbox.handoff(key)
+            self.active.discard(key)
+        self.emit("handoff" if succeeded else "attempt_failed", id=message_id)
+
+    def pump(self):
+        with self.lock:
+            for item in self.mailbox.pending(time.time()):
+                key, obj = item["key"], item["envelope"]
+                if key in self.active:
+                    continue
+                dest_hash = bytes.fromhex(obj["destination"])
+                # Native LXMF can reuse a backchannel even without a cached route.
+                if RNS.Identity.recall(dest_hash) is None:
+                    RNS.Transport.request_path(dest_hash)
+                    self.emit("no_path", id=obj["id"])
+                    continue
+                self.mailbox.begin_attempt(key, time.time())
+                self.active.add(key)
+                success = lambda m, k=key, i=obj["id"]: self._complete(k, i, True)
+                failure = lambda m, k=key, i=obj["id"]: self._complete(k, i, False)
+                try:
+                    sent = self.transmit(obj["destination"], encode(obj), success, failure)
+                    if not sent:
+                        self.active.discard(key)
+                except Exception:
+                    self.active.discard(key)
+                    raise

dethron/assembly.py

@@ -0,0 +1,86 @@
+"""Transactional partial assembly with bounded retained evidence."""
+import base64
+from contextlib import contextmanager
+import hashlib
+import json
+import sqlite3
+
+from .parts import validate
+from .erasure import reconstruct
+from .protocol import decode, encode
+
+
+class Assembly:
+    def __init__(self, path, identity, max_bytes=8*1024*1024):
+        self.path, self.identity, self.max_bytes = path, identity, max_bytes
+        with self.transaction() as db:
+            db.execute("CREATE TABLE IF NOT EXISTS owner(identity TEXT,version INTEGER)")
+            owner = db.execute("SELECT * FROM owner").fetchone()
+            if owner and owner != (identity, 1):
+                raise ValueError("assembly identity/schema mismatch")
+            if not owner:
+                db.execute("INSERT INTO owner VALUES (?,1)", (identity,))
+            db.execute("CREATE TABLE IF NOT EXISTS objects(key TEXT PRIMARY KEY,manifest BLOB,expires INTEGER,result BLOB)")
+            db.execute("CREATE TABLE IF NOT EXISTS parts(key TEXT,idx INTEGER,data BLOB,wire BLOB,PRIMARY KEY(key,idx))")
+
+    @contextmanager
+    def transaction(self):
+        db = sqlite3.connect(self.path, timeout=5, isolation_level=None)
+        try:
+            db.execute("PRAGMA journal_mode=DELETE")
+            db.execute("PRAGMA synchronous=FULL")
+            db.execute("BEGIN IMMEDIATE")
+            yield db
+            db.commit()
+        except BaseException:
+            db.rollback()
+            raise
+        finally:
+            db.close()
+
+    def accept_verified(self, envelope, wire, now):
+        obj = decode(encode(envelope), now)
+        if obj["kind"] != "data" or obj["destination"] != self.identity:
+            raise ValueError("not local authenticated data")
+        manifest, index, content = validate(base64.b64decode(obj["payload"], validate=True))
+        key = "/".join([obj["source"], obj["destination"], manifest["id"]])
+        encoded = encode(manifest)
+        with self.transaction() as db:
+            existing = db.execute("SELECT manifest,expires FROM objects WHERE key=?", (key,)).fetchone()
+            if existing and existing != (encoded, obj["expires"]):
+                raise ValueError("incompatible manifest or lifetime")
+            if not existing:
+                if db.execute("SELECT count(*) FROM objects").fetchone()[0] >= 16:
+                    raise ValueError("object count limit")
+                db.execute("INSERT INTO objects VALUES (?,?,?,NULL)", (key, encoded, obj["expires"]))
+            previous = db.execute("SELECT data FROM parts WHERE key=? AND idx=?", (key, index)).fetchone()
+            fresh = previous is None
+            if previous and previous[0] != content:
+                raise ValueError("conflicting part")
+            if fresh:
+                db.execute("INSERT INTO parts VALUES (?,?,?,?)", (key, index, content, wire))
+            chunks = dict(db.execute("SELECT idx,data FROM parts WHERE key=? ORDER BY idx", (key,)))
+            joined = reconstruct(manifest, chunks)
+            complete = joined is not None
+            if complete:
+                db.execute("UPDATE objects SET result=? WHERE key=?", (joined, key))
+            used = db.execute("SELECT COALESCE(SUM(length(manifest)+COALESCE(length(result),0)),0) FROM objects").fetchone()[0]
+            used += db.execute("SELECT COALESCE(SUM(length(data)+length(wire)),0) FROM parts").fetchone()[0]
+            if used > self.max_bytes:
+                raise ValueError("assembly capacity exceeded")
+            return {"key": key, "id": manifest["id"], "count": len(chunks), "complete": complete,
+                    "fresh": fresh, "digest": manifest["digest"], "size": manifest["size"]}
+
+    def content(self, key):
+        with self.transaction() as db:
+            row = db.execute("SELECT result FROM objects WHERE key=?", (key,)).fetchone()
+            return row[0] if row else None
+
+    def snapshot(self):
+        with self.transaction() as db:
+            result = []
+            for key, raw, content in db.execute("SELECT key,manifest,result FROM objects"):
+                m = json.loads(raw)
+                count = db.execute("SELECT count(*) FROM parts WHERE key=?", (key,)).fetchone()[0]
+                result.append({"id": m["id"], "count": count, "complete": content is not None})
+            return result

dethron/audit.py

@@ -0,0 +1,107 @@
+"""Recompute every proof a node directory holds, trusting nothing that produced it.
+
+This is deliberately separate from the code that obtains proofs. An auditor that shares
+its assumptions with the thing it audits is a formality. Everything here reads files and
+checks signatures; it never asks a node what happened.
+
+Each packet is checked inside the validity window it declared for itself. A proof that was
+sound when it was made does not stop being sound when it expires, and a verifier that said
+otherwise would quietly discard old evidence.
+"""
+import hashlib
+import json
+from pathlib import Path
+import time
+
+import RNS
+
+from . import custody as attestation
+from .endpoint import parse_contact
+from .wire import authenticate, declared_expiry
+
+
+def verify_directory(home):
+    """Return a report: every check, whether it passed, and what it proves.
+
+    The report is data, not a verdict to be taken on faith: each entry names the file it
+    came from so a reader can repeat the check by hand.
+    """
+    home = Path(home)
+    if not (home/'identity').exists():
+        return {'home': str(home), 'verdict': 'nothing to verify',
+                'hint': 'no identity here; run send or fetch in this directory first',
+                'checks': []}
+    identity = RNS.Identity.from_file(str(home/'identity'))
+    mine = RNS.Destination.hash(identity, 'lxmf', 'delivery').hex()
+    checks = _object(home)+_custody(home, mine)+_receipts(home, mine)
+    if not checks:
+        return {'home': str(home), 'verdict': 'nothing to verify', 'checks': [],
+                'hint': 'no proofs here yet; run send or fetch in this directory first'}
+    passed = all(check['passed'] for check in checks)
+    return {'home': str(home), 'verdict': 'pass' if passed else 'fail', 'checks': checks}
+
+
+def _object(home):
+    """What was reconstructed must be what the receipt was issued over."""
+    output, completion = home/'output.bin', home/'completion.json'
+    if not (output.exists() and completion.exists()):
+        return []
+    envelope = json.loads(completion.read_text(encoding='utf-8'))
+    digest = hashlib.sha256(output.read_bytes()).hexdigest()
+    return [{'check': 'the reconstructed object matches the receipt issued for it',
+             'passed': digest == envelope.get('digest'), 'file': output.name,
+             'sha256': digest, 'bytes': output.stat().st_size}]
+
+
+def _custody(home, mine):
+    """Proof of entry: signed by the relay that was asked, for this message, to us."""
+    checks = []
+    for packet in sorted((home/'custody').glob('*.lxmf')) if (home/'custody').exists() else []:
+        transient_id = packet.name.split('.')[0]
+        refused = packet.name.endswith('.refused.lxmf')
+        label = ('refusal' if refused else 'custody')+f' {transient_id[:8]}'
+        sidecar = packet.with_suffix('.relay')
+        if not sidecar.exists():
+            checks.append({'check': f'{label} names the relay that signed it', 'passed': False,
+                           'file': packet.name,
+                           'error': 'no relay contact was recorded beside the packet'})
+            continue
+        raw = packet.read_bytes()
+        try:
+            _, key = parse_contact(sidecar.read_text(encoding='utf-8'))
+            check = attestation.verify_refusal if refused else attestation.verify
+            obj = check(raw, bytes.fromhex(key), mine, transient_id, declared_expiry(raw)-1)
+            checks.append({'check': f'{label} is signed by the relay that was asked',
+                           'passed': True, 'file': packet.name,
+                           'proves': 'no entry' if refused else 'entry',
+                           **{k: obj[k] for k in ('stored_size', 'reason') if k in obj}})
+        except Exception as exc:
+            checks.append({'check': label, 'passed': False, 'file': packet.name,
+                           'error': repr(exc)})
+    return checks
+
+
+def _receipts(home, mine):
+    """Proof of exit: signed by a recipient this node actually sent to, over these bytes."""
+    path = home/'recipients.json'
+    recipients = json.loads(path.read_text(encoding='utf-8')) if path.exists() else {}
+    checks = []
+    for packet in sorted((home/'receipts').glob('*.lxmf')) if (home/'receipts').exists() else []:
+        raw, found = packet.read_bytes(), None
+        for destination, key in recipients.items():
+            try:
+                found = (destination, authenticate(raw, bytes.fromhex(key), mine,
+                                                   declared_expiry(raw)-1))
+                break
+            except Exception:
+                continue
+        if found is None:
+            checks.append({'check': f'receipt {packet.stem[:8]} is signed by a known recipient',
+                           'passed': False, 'file': packet.name,
+                           'error': 'no recipient this node sent to could have signed it'})
+            continue
+        destination, obj = found
+        checks.append({'check': f'receipt {packet.stem[:8]} is signed by the recipient sent to',
+                       'passed': obj.get('kind') == 'receipt', 'file': packet.name,
+                       'proves': 'exit', 'recipient': destination, 'digest': obj.get('digest')})
+    return checks

dethron/cli.py

@@ -0,0 +1,170 @@
+"""The command line: mint an identity, run a relay, send an object, fetch it, check the proofs.
+
+Five commands are enough to exercise the whole claim, and none of them hides a step. `send`
+returns a signed custody attestation or says why there is none. `fetch` returns the exact
+bytes or says what is still missing. `verify` recomputes from the files on disk, trusting
+nothing that any earlier command printed.
+
+    dethron identity ./alice
+    dethron relay ./relay --port 45810
+    dethron send ./alice --to <contact> --relay <host:port/propagation> report.pdf
+    dethron fetch ./bob --from <contact> --relay <host:port/propagation>
+    dethron receipts ./alice --relay <host:port/propagation>
+    dethron verify ./bob
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import sys
+import time
+
+from .node import Node, parse_contact, parse_relay
+
+ANNOUNCE_SECONDS = 30
+
+
+def show(**values):
+    print(json.dumps(values, indent=2), flush=True)
+    return 0
+
+
+def identity(args):
+    """An address is knowable before a node ever starts, so contacts can be exchanged first."""
+    import RNS
+    home = Path(args.home)
+    home.mkdir(parents=True, exist_ok=True)
+    key = home/'identity'
+    existed = key.exists()
+    if existed:
+        one = RNS.Identity.from_file(str(key))
+    else:
+        one = RNS.Identity()
+        one.to_file(str(key))
+    delivery = RNS.Destination.hash(one, 'lxmf', 'delivery').hex()
+    return show(home=str(home), created=not existed,
+                contact=f'{delivery}.{one.get_public_key().hex()}',
+                propagation=RNS.Destination.hash(one, 'lxmf', 'propagation').hex())
+
+
+def relay(args):
+    """Hold objects for recipients who are not here yet, and attest to what is held."""
+    with Node(args.home, relay=True, port=args.port, peers=args.peer, name='relay') as node:
+        show(contact=node.contact, propagation=node.propagation,
+             relay=f'<this host>:{args.port}/{node.propagation}')
+        print('running; Ctrl-C to stop', file=sys.stderr, flush=True)
+        try:
+            while True:
+                node.announce()
+                time.sleep(ANNOUNCE_SECONDS)
+        except KeyboardInterrupt:
+            print('stopping', file=sys.stderr, flush=True)
+    return 0
+
+
+def send(args):
+    """Hand an object to a relay and come back with proof that the relay took it."""
+    from .parts import split
+    from .protocol import data_envelope, encode
+    endpoint, propagation = parse_relay(args.relay)
+    destination, _ = parse_contact(args.to)
+    content = Path(args.file).read_bytes()
+    with Node(args.home, peers=[endpoint], name='origin') as node:
+        node.announce()
+        origin = node.source.hash.hex()
+        part = split(content, 1, hashlib.sha256(content).hexdigest()[:32])[0]
+        envelope = data_envelope(origin, destination, encode(part), int(time.time())+args.expires)
+        handoff = node.send(encode(envelope), to=args.to, via=propagation, timeout=args.timeout)
+        proof = node.custody_of(handoff['transient_id'], relay=args.relay_contact,
+                                timeout=args.timeout) if args.relay_contact else None
+        return show(contact=node.contact, size=len(content),
+                    sha256=hashlib.sha256(content).hexdigest(),
+                    transient_id=handoff['transient_id'], packed_bytes=handoff['packed_bytes'],
+                    proof_of_entry=proof and proof['event'] == 'custody_received',
+                    custody=proof)
+
+
+def fetch(args):
+    """Ask a relay for what it holds for us, reconstruct, and write a receipt."""
+    endpoint, propagation = parse_relay(args.relay)
+    with Node(args.home, receive=True, peers=[endpoint], name='recipient') as node:
+        node.announce()
+        state = node.fetch(source=args.source, via=propagation, timeout=args.timeout)
+        receiver = state.get('receiver') or {}
+        if receiver.get('completed') and args.receipt_to:
+            node.publish_receipt(to=args.receipt_to, via=propagation, timeout=args.timeout)
+        return show(contact=node.contact, completed=bool(receiver.get('completed')),
+                    sha256=receiver.get('sha256'), output=str(Path(args.home)/'output.bin'),
+                    sync=state.get('sync'), objects=receiver.get('objects'))
+
+
+def receipts(args):
+    """Come back after being away and collect the proofs a relay is holding for us."""
+    endpoint, propagation = parse_relay(args.relay)
+    with Node(args.home, peers=[endpoint], name='origin') as node:
+        node.announce()
+        state = node.collect(via=propagation, timeout=args.timeout)
+        return show(contact=node.contact, collected=state['collected'],
+                    receipts=state['receipts'], sync=state['sync'])
+
+
+def verify(args):
+    """Recompute the proofs held here. The checking itself lives in `audit`, on purpose:
+    an auditor that shares a module with what it audits is a formality."""
+    from .audit import verify_directory
+    report = verify_directory(args.home)
+    show(**report)
+    return 0 if report['verdict'] != 'fail' else 1
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog='dethron', description=__doc__.split('\n')[0])
+    subs = parser.add_subparsers(dest='command', required=True)
+
+    one = subs.add_parser('identity', help='mint or show a node identity and its contact')
+    one.add_argument('home')
+    one.set_defaults(run=identity)
+
+    two = subs.add_parser('relay', help='hold objects for recipients who are not here yet')
+    two.add_argument('home')
+    two.add_argument('--port', type=int, required=True, help='TCP port to listen on')
+    two.add_argument('--peer', action='append', default=[], help='host:port of another node')
+    two.set_defaults(run=relay)
+
+    three = subs.add_parser('send', help='hand an object to a relay and obtain proof of entry')
+    three.add_argument('home')
+    three.add_argument('file')
+    three.add_argument('--to', required=True, help='the recipient contact')
+    three.add_argument('--relay', required=True, help='host:port/<propagation address>')
+    three.add_argument('--relay-contact', help="the relay's contact, to ask it for custody")
+    three.add_argument('--expires', type=int, default=7200, help='seconds until the object expires')
+    three.add_argument('--timeout', type=int, default=120)
+    three.set_defaults(run=send)
+
+    four = subs.add_parser('fetch', help='collect what a relay holds and reconstruct it')
+    four.add_argument('home')
+    four.add_argument('--source', required=True, help="the sender's contact")
+    four.add_argument('--relay', required=True, help='host:port/<propagation address>')
+    four.add_argument('--receipt-to', help="publish the receipt back to the sender's contact")
+    four.add_argument('--timeout', type=int, default=180)
+    four.set_defaults(run=fetch)
+
+    six = subs.add_parser('receipts', help='collect the receipts a relay holds for us')
+    six.add_argument('home')
+    six.add_argument('--relay', required=True, help='host:port/<propagation address>')
+    six.add_argument('--timeout', type=int, default=180)
+    six.set_defaults(run=receipts)
+
+    five = subs.add_parser('verify', help='recompute the proofs held in a node directory')
+    five.add_argument('home')
+    five.set_defaults(run=verify)
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    return args.run(args) or 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

dethron/config.py

@@ -0,0 +1,39 @@
+"""The Reticulum configuration a node runs on, written where the node lives.
+
+Reticulum reads its configuration from a directory, so a node that carries its own
+directory carries its own network with it: two nodes on one machine do not collide, and
+moving a node means moving a folder. Nothing here is shared and nothing is discovered —
+a node reaches exactly the peers it was told about, which is what makes a claim about
+the medium checkable later.
+"""
+
+BASE = ('[reticulum]\n share_instance = No\n enable_transport = {transport}\n'
+        ' discover_interfaces = No\n[logging]\n loglevel = {loglevel}\n[interfaces]\n')
+
+
+def config_text(*, port=None, peers=(), serial=None, transport=False, loglevel=3):
+    """`port` listens, `peers` are host:port to dial, `serial` is a port that carries no IP.
+
+    A node given a serial link and nothing else has exactly one interface, and it is not
+    an IP one. That is not decoration: it is what lets an audit say an object crossed a
+    non-IP medium, because the node had no other medium to cross.
+    """
+    if serial and (port or peers):
+        raise ValueError('a serial-only node cannot also listen on or dial an IP address')
+    text = BASE.format(transport='Yes' if transport else 'No', loglevel=int(loglevel))
+    if port:
+        text += (' [[Listener]]\n type = TCPServerInterface\n enabled = Yes\n'
+                 f' listen_ip = 0.0.0.0\n listen_port = {int(port)}\n')
+    for index, peer in enumerate(peers):
+        host, _, remote = str(peer).partition(':')
+        if not host or not remote.isdigit():
+            raise ValueError(f'a peer is host:port, not {peer!r}')
+        text += (f' [[Peer{index}]]\n type = TCPClientInterface\n enabled = Yes\n'
+                 f' target_host = {host}\n target_port = {int(remote)}\n')
+    if serial:
+        text += (' [[Serial]]\n type = SerialInterface\n enabled = Yes\n'
+                 f" port = {serial['port']}\n speed = {int(serial.get('speed', 115200))}\n"
+                 ' databits = 8\n parity = N\n stopbits = 1\n')
+    if not (port or peers or serial):
+        raise ValueError('a node with no interface can reach nothing; give a port, a peer or a serial link')
+    return text

dethron/custody.py

@@ -0,0 +1,78 @@
+"""Proof of entry: a relay attests, by transient id, that it holds a message.
+
+A custody attestation is a claim by the relay. It proves the message was
+confided to the network; it never proves delivery. Only the recipient's
+receipt does that.
+"""
+import hashlib
+import time
+import uuid
+
+from RNS.vendor import umsgpack
+
+from .protocol import decode, encode
+from .wire import authenticate
+
+LIFETIME = 3600
+
+
+def request(origin, relay, transient_id, public_key, expires=None, request_id=None):
+    obj = {"version": 1, "kind": "custody_request", "id": request_id or uuid.uuid4().hex,
+           "source": origin, "destination": relay, "expires": expires or int(time.time())+LIFETIME,
+           "transient_id": transient_id, "public_key": public_key}
+    return decode(encode(obj), 0)
+
+
+def attest(req, relay, recipient, stored, received):
+    """Built by the relay from the bytes it actually holds on disk."""
+    obj = {"version": 1, "kind": "custody", "id": req["id"], "source": relay,
+           "destination": req["source"], "expires": req["expires"],
+           "transient_id": req["transient_id"], "recipient": recipient,
+           "stored_size": len(stored), "stored_digest": hashlib.sha256(stored).hexdigest(),
+           "received": int(received)}
+    return decode(encode(obj), 0)
+
+
+def refuse(req, relay, reason):
+    """Absence of custody must be explicit, never silence."""
+    obj = {"version": 1, "kind": "custody_refusal", "id": req["id"], "source": relay,
+           "destination": req["source"], "expires": req["expires"],
+           "transient_id": req["transient_id"], "reason": reason}
+    return decode(encode(obj), 0)
+
+
+def peek(raw, now):
+    """Untrusted look at the envelope inside a packed LXMF message, only to pick a key."""
+    if not isinstance(raw, bytes) or len(raw) < 97:
+        raise ValueError("short packet")
+    return decode(umsgpack.unpackb(raw[96:])[2], now)
+
+
+def accept_request(raw, relay, now, known=None):
+    """The requester's key comes from the announce cache or from the request itself;
+    either way the LXMF signature must bind that key to the packet's source hash."""
+    try:
+        key = known if known is not None else bytes.fromhex(peek(raw, now)["public_key"])
+    except Exception as exc:
+        raise ValueError(f"unreadable custody request: {exc}") from exc
+    obj = authenticate(raw, key, relay, now)
+    if obj["kind"] != "custody_request" or obj["public_key"] != key.hex():
+        raise ValueError("not a custody request signed by its declared key")
+    return obj, key
+
+
+def verify(raw, relay_public_key, origin, transient_id, now):
+    """Only a signed custody envelope for exactly this transient id counts as proof of entry."""
+    obj = authenticate(raw, relay_public_key, origin, now)
+    if obj["kind"] != "custody":
+        raise ValueError(f"not a custody attestation: {obj['kind']}")
+    if obj["transient_id"] != transient_id:
+        raise ValueError("custody attests a different message")
+    return obj
+
+
+def verify_refusal(raw, relay_public_key, origin, transient_id, now):
+    obj = authenticate(raw, relay_public_key, origin, now)
+    if obj["kind"] != "custody_refusal" or obj["transient_id"] != transient_id:
+        raise ValueError("not a refusal for this message")
+    return obj

dethron/database.py

@@ -0,0 +1,56 @@
+"""Bounded application mailbox, independent from the native LXMF propagation store."""
+from contextlib import contextmanager
+import sqlite3
+
+from .protocol import encode
+
+
+def row_key(direction, obj):
+    return "/".join([direction, obj["source"], obj["destination"], obj["id"], obj["kind"]])
+
+
+class Database:
+    def __init__(self, path, identity, max_rows=128, max_bytes=8*1024*1024):
+        self.path, self.identity = path, identity
+        self.max_rows, self.max_bytes = max_rows, max_bytes
+        with self.transaction() as db:
+            db.execute("CREATE TABLE IF NOT EXISTS metadata (identity TEXT, version INTEGER)")
+            row = db.execute("SELECT identity,version FROM metadata").fetchone()
+            if row and tuple(row) != (identity, 1):
+                raise ValueError("mailbox identity/schema mismatch")
+            if not row:
+                db.execute("INSERT INTO metadata VALUES (?,1)", (identity,))
+            db.execute("""CREATE TABLE IF NOT EXISTS messages (
+                key TEXT PRIMARY KEY, direction TEXT, body BLOB NOT NULL,
+                state TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+                wire BLOB NOT NULL DEFAULT X'')""")
+
+    @contextmanager
+    def transaction(self):
+        db = sqlite3.connect(self.path, timeout=5, isolation_level=None)
+        db.row_factory = sqlite3.Row
+        try:
+            db.execute("PRAGMA journal_mode=DELETE")
+            db.execute("PRAGMA synchronous=FULL")
+            db.execute("BEGIN IMMEDIATE")
+            yield db
+            db.commit()
+        except BaseException:
+            db.rollback()
+            raise
+        finally:
+            db.close()
+
+    def insert(self, db, direction, obj, state, wire=b""):
+        key, body = row_key(direction, obj), encode(obj)
+        existing = db.execute("SELECT body FROM messages WHERE key=?", (key,)).fetchone()
+        if existing:
+            if existing["body"] != body:
+                raise ValueError("message ID conflicts with persisted content")
+            return False
+        count, used = db.execute("SELECT COUNT(*), COALESCE(SUM(length(body)+length(wire)),0) FROM messages").fetchone()
+        if count >= self.max_rows or used+len(body)+len(wire) > self.max_bytes:
+            raise ValueError("mailbox capacity exceeded")
+        db.execute("INSERT INTO messages(key,direction,body,state,wire) VALUES (?,?,?,?,?)",
+                   (key, direction, body, state, wire))
+        return True