Index

mesh

Device Mesh — this Diapason installation among the user's other devices.

The mesh sits ABOVE the domain, never inside it: Succès remains the single source of truth for tasks, projects and notes (spec §34), and the mesh only answers three questions the domain cannot — which devices exist, which are reachable, and what may be asked of them.

Layers, built in this order: * identity — this device's Ed25519 key pair and derived device id. * (next) registry — the devices this one has paired with. * (next) presence / commands — reachability and the signed bus.

Classes

DeviceIdentity dataclass

DeviceIdentity(
    device_id: str,
    public_key: bytes,
    name: str,
    platform: str,
    created_at_ms: int,
)

This device, as the rest of the mesh may know it.

Methods:

to_public_dict

to_public_dict() -> dict[str, Any]

Everything shareable — and nothing else. No private key, ever.

Source code in src/diapason/mesh/identity.py

def to_public_dict(self) -> dict[str, Any]:
    """Everything shareable — and nothing else. No private key, ever."""
    return {
        "deviceId": self.device_id,
        "publicKey": self.public_key_b64,
        "name": self.name,
        "platform": self.platform,
        "createdAtMs": self.created_at_ms,
        "ownerId": owner_id(),
    }

Functions:

device_identity

device_identity(*, name: str = '') -> DeviceIdentity

This device's identity, creating the key pair on first call.

Idempotent: subsequent calls read what the first one wrote. The private key is generated once and never regenerated silently — a device whose key changed would be, to every peer, a different device.

Source code in src/diapason/mesh/identity.py

def device_identity(*, name: str = "") -> DeviceIdentity:
    """This device's identity, creating the key pair on first call.

    Idempotent: subsequent calls read what the first one wrote. The private
    key is generated once and never regenerated silently — a device whose key
    changed would be, to every peer, a different device.
    """
    from diapason.security.signing import generate_keypair

    directory = identity_dir()
    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
    try:
        directory.chmod(0o700)
    except OSError:  # noqa: BLE001 - a stricter umask is fine
        pass

    key_path = directory / _KEY_FILENAME
    manifest_path = directory / _MANIFEST_FILENAME

    if key_path.exists() and manifest_path.exists():
        # Read the private key for its side effects only: it re-asserts 0600
        # and refuses a swapped symlink, so a tampered key fails HERE rather
        # than at the first signature, when a command is already in flight.
        _read_private_key(key_path)
        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
        return DeviceIdentity(
            device_id=str(manifest["deviceId"]),
            public_key=base64.b64decode(manifest["publicKey"]),
            name=str(manifest.get("name") or _default_name()),
            platform=str(manifest.get("platform") or _default_platform()),
            created_at_ms=int(manifest.get("createdAtMs") or _now_ms()),
        )

    keypair = generate_keypair()
    device_id = _legacy_succes_device_id() or _fingerprint(keypair.public_key)
    identity = DeviceIdentity(
        device_id=device_id,
        public_key=keypair.public_key,
        name=name or _default_name(),
        platform=_default_platform(),
        created_at_ms=_now_ms(),
    )
    # Key first, manifest second: a crash between the two is recoverable
    # (the half-written pair is detected by the exists() check above and
    # regenerated), whereas a manifest without its key is not.
    if not key_path.exists():
        _write_private_key(key_path, keypair.private_key)
    manifest_path.write_text(
        json.dumps(identity.to_public_dict(), ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    try:
        manifest_path.chmod(0o600)
    except OSError:  # noqa: BLE001
        pass
    return identity

public_identity

public_identity() -> dict[str, Any]

What this device may publish about itself.

Source code in src/diapason/mesh/identity.py

def public_identity() -> dict[str, Any]:
    """What this device may publish about itself."""
    return device_identity().to_public_dict()

sign_envelope

sign_envelope(payload: dict[str, Any]) -> str

Sign payload with this device's private key. Returns base64.

Source code in src/diapason/mesh/identity.py

def sign_envelope(payload: dict[str, Any]) -> str:
    """Sign *payload* with this device's private key. Returns base64."""
    from diapason.security.signing import sign_b64

    directory = identity_dir()
    device_identity()  # ensure the pair exists before reading it
    private_key = _read_private_key(directory / _KEY_FILENAME)
    return sign_b64(canonical_bytes(payload), private_key)

verify_envelope

verify_envelope(
    payload: dict[str, Any],
    signature_b64: str,
    public_key: bytes,
) -> bool

True when signature_b64 is this payload, signed by public_key.

Source code in src/diapason/mesh/identity.py

def verify_envelope(
    payload: dict[str, Any], signature_b64: str, public_key: bytes
) -> bool:
    """True when *signature_b64* is this payload, signed by *public_key*."""
    from diapason.security.signing import verify_b64

    if not signature_b64:
        return False
    return verify_b64(canonical_bytes(payload), signature_b64, public_key)