Bonding collar — conferring with an OS capability layer
bonding_collar.py is the SLeeLa-side bonding collar: the careful
negotiator a SLeeLa executable uses to discover, on a new or otherwise
unknown operating system, whether the host confers a real advantage — and to
bond with it only as far as both sides can prove.
It is the client half of a capability confer. A conforming host responder — for example a TAC3-class filesystem/OS layer — may attest to the capability names below; the collar independently verifies that attestation and decides the tier. TAC3 is the operator's own creation; this collar contains none of its internals and does not depend on it.
What it does
- Probe — look for a host capability responder; never assume one exists.
- Confer — exchange MAC-backed capability offers (same keyed-MAC primitive,
siphash24, as the HTTP 3.0 capability handshake). - Bond — agree on the highest tier both sides attest to, under a shared secret.
- Fail closed — on any unknown, unattested, or untrusted host, drop to
NONEand run in SLeeLa's safe, host-agnostic mode.
Capability tiers (negotiated by name, never by host internals)
| Tier | Name | Meaning (advantage conferred) |
|---|---|---|
0x00 | NONE | No attested advantage — safe baseline / unknown OS |
0x01 | T1_PRESENT | A capability responder is present and attested |
0x02 | T2_STORAGE | Durable / redundant storage advantage available |
0x04 | T3_CONTEXT | Contextual-identity / health metadata available |
0x08 | T4_RECOVERY | Protected boot/recovery + integrity attestation |
Tiers are cumulative and describe what advantage a host confers, never
how it implements it. CAP_BASELINE = T1_PRESENT.
Protecting our advantage (the design contract)
This is deliberately the client side only, and it embeds no proprietary OS/filesystem internals — no on-disk format, no kernel structures, no host-specific field layouts or magic numbers. It negotiates purely by neutral capability names plus an opaque, MAC-attested tag. Therefore:
- On a trusted, attested host, the collar unlocks the advantage tiers.
- On a new / unknown / hostile host, the collar reveals nothing proprietary
and drops to
NONE— so probing can never leak our advantage.
The collar tells SLeeLa whether an advantage is present and which tier to use. It never encodes how the host provides it.
Fail-closed rules
confer() returns NONE (not bonded) when:
- there is no responder / no offer (unknown OS);
- the offer's protocol does not match;
- the offer's attestation MAC fails (untrusted host, or caps tampered after signing);
- there is no common baseline capability.
Otherwise it bonds at the highest mutually-attested tier — and never above the local collar's own declared support (we never advertise more than we have).
Usage
from bonding_collar import BondingCollar, probe_env_responder, CAP_ALL, CAP_T2_STORAGE
collar = BondingCollar(local_caps=CAP_ALL, key=shared_secret) # 16-byte key
result = collar.confer(probe_env_responder(shared_secret))
if result.bonded and result.tier >= CAP_T2_STORAGE:
... # safe to use the durable-storage advantage
else:
... # unknown/untrusted host -> run host-agnostic baseline
print(result.tier_name, "-", result.reason)
The bundled probe probe_env_responder() is intentionally conservative: it
reads an attestation from the environment (SLEELA_OS_CAPS,
SLEELA_OS_CAP_MAC), makes no privileged calls, mounts nothing, and loads no
host code, and returns None when the host provides nothing (→ fail closed).
A deployment may add richer responders (a well-known device node or socket); the
contract is unchanged — return a CollarOffer the collar will independently
MAC-verify, or None.
Run the self-demo
cd http-3.0 && python3 bonding_collar.py
It shows the three canonical outcomes: unknown OS → fail closed; attested host → bond at the highest common tier; forged host (wrong key) → fail closed.
Relationship to the HTTP 3.0 handshake
The collar mirrors the shape of the H3 capability handshake in
http3_flow.py (CapOffer / handshake_negotiate) — MAC-backed
offers, a cumulative tier bitmask, and a baseline fallback — but negotiates
OS/host advantage rather than transport behavior, with its own domain tag
(SLBC) so the two handshakes can never be confused.