12. Keystore & Enclave (fleetmesh_node.keystore)

The fleetmesh_node.keystore package manages cryptographic private keys, seed phrases, key derivation paths, and hardware security enclave integration.

12.1. Keystore Core

The node’s keys on disk.

One JSON file, mode 0600, holding the three secrets constants.json names: the secp256k1 node key (the nostr identity and did:nostr subject), the X25519 agreement key, and the Ed25519 transport key. Generated once, read every start. Nothing else is stored here: grants, receipts and the event store have their own files, and an operator who rotates the node key has a new node.

class fleetmesh_node.keystore.core.Keystore[source]

Bases: object

__init__(node_sk, agreement_seed, transport_seed)[source]
Parameters:
Return type:

None

node_sk: str
node_pk: str
did: str
agreement_priv: X25519PrivateKey
agreement_pub: X25519PublicKey
transport_priv: Ed25519PrivateKey
transport_pub: Ed25519PublicKey
multikeys()[source]
Return type:

dict[str, str]

kid(which='agreement')[source]
Parameters:

which (Literal['agreement', 'transport', 'node'])

Return type:

str

classmethod generate()[source]
Return type:

Keystore

classmethod load(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

Keystore

save(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

str

classmethod load_or_generate(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

Keystore

12.2. Hardware Enclave Integration

Enclave-shaped DID keystore: WebAuthn/COSE wire formats over a software key.

What this module does: 1. Generates a P-256 (or secp256k1) key with cryptography, holds it in process

memory and writes it to disk as priv_hex under the node directory.

  1. Produces WebAuthn-shaped structures - authenticatorData, clientDataJSON, COSE EC2 keys - and a self-signed attestation statement, with no external dependency beyond cryptography.

  2. EnclaveKeystore: a drop-in for Keystore that tags the events it signs [‘enclave’, hardware_tier, pubkey_multibase, attestation_sig_hex] and adds the key to the DID document’s verification methods.

What it does not do, stated plainly so nobody relies on it: - No Secure Enclave, TPM or FIDO authenticator API is driven. The key never

leaves software. detect_hardware_enclave() only reports the platform (apple-secure-enclave on Darwin/arm64 means “this host has one”, not “the key is in it”); on every other host the tier reads emulated-enclave.

  • The attestation is self-asserted: the statement is signed by the same software key it attests, and user_presence / user_verified are fixed True with no biometric or presence check behind them. A peer verifying it learns only that the ECDSA signature is valid.

Verifiers must treat the enclave tag as a key-format hint, not as hardware provenance. A real hardware backend (and honest tier names) is tracked in docs/architecture-review-2026-10-06.md R8.

fleetmesh_node.keystore.enclave.detect_hardware_enclave()[source]

Detect available hardware security enclave capabilities on the host.

Return type:

Mapping[str, Any]

class fleetmesh_node.keystore.enclave.EnclaveSignature[source]

Bases: object

Hardware enclave signature with attestation metadata.

__init__(raw_signature, der_signature, attestation)[source]
Parameters:
Return type:

None

property hex: str
to_dict()[source]
Return type:

Mapping[str, Any]

class fleetmesh_node.keystore.enclave.EnclaveKey[source]

Bases: object

Hardware Enclave-protected asymmetric keypair.

__init__(key_id, priv_key, key_type='p256', hardware_tier=None)[source]
Parameters:
  • key_id (str)

  • priv_key (EllipticCurvePrivateKey | str)

  • key_type (str)

  • hardware_tier (str | None)

Return type:

None

property public_key_hex: str
property x_only_hex: str
cose_key()[source]

Convert public key into standard COSE_Key structure (RFC 8152).

Return type:

dict[int, Any]

sign(message, challenge=None)[source]

Sign message inside enclave isolation, returning signature + hardware attestation.

Parameters:
Return type:

EnclaveSignature

verify(message, signature_bytes)[source]

Verify signature (either 64-byte raw or DER format) against this key.

Parameters:
Return type:

bool

classmethod generate(key_type='p256', hardware_tier=None)[source]
Parameters:
  • key_type (str)

  • hardware_tier (str | None)

Return type:

EnclaveKey

class fleetmesh_node.keystore.enclave.WebAuthnCredential[source]

Bases: object

W3C WebAuthn Level 3 Passkey Credential.

__init__(credential_id, rp_id, user_name, enclave_key, sign_count=0)[source]
Parameters:
Return type:

None

property credential_id_hex: str
property credential_id_b64: str
make_attestation_object()[source]

Produce WebAuthn attestationObject (CBOR map: fmt, authData, attStmt).

Return type:

bytes

create_assertion(challenge, origin='https://meshnode.example.org', user_verification=True)[source]

Produce WebAuthn authentication assertion (response to navigator.credentials.get).

Parameters:
Return type:

Mapping[str, Any]

verify_assertion(assertion, expected_challenge, expected_origin='https://meshnode.example.org')[source]

Verify WebAuthn authentication assertion against credential public key.

Parameters:
Return type:

bool

classmethod register(rp_id='meshnode.example.org', user_name='meshnode-operator', hardware_tier=None)[source]
Parameters:
  • rp_id (str)

  • user_name (str)

  • hardware_tier (str | None)

Return type:

WebAuthnCredential

class fleetmesh_node.keystore.enclave.EnclaveKeystore[source]

Bases: object

Hardware-Enclave augmented Keystore implementing KeyStoreProtocol.

FILE: str = 'keys.json'
__init__(node_sk, agreement_seed, transport_seed, enclave_key=None, hardware_tier=None)[source]
Parameters:
Return type:

None

multikeys()[source]

Multikeys for node descriptor and DID document, including hardware enclave key.

Return type:

dict[str, str]

kid(which='agreement')[source]
Parameters:

which (str)

Return type:

str

sign_event_with_attestation(created_at, kind, tags, content)[source]

Create signed Nostr event with attached in-band hardware enclave attestation tag.

Parameters:
Return type:

NostrEvent

attest_event(event)[source]

Produce detached hardware attestation receipt over an already-formed event ID.

Parameters:

event (NostrEvent | Mapping[str, Any])

Return type:

Mapping[str, Any]

save(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

str

classmethod load(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

EnclaveKeystore

classmethod generate(hardware_tier=None, key_type='p256')[source]
Parameters:
  • hardware_tier (str | None)

  • key_type (str)

Return type:

EnclaveKeystore

classmethod load_or_generate(directory)[source]
Parameters:

directory (str | PathLike[str])

Return type:

EnclaveKeystore

fleetmesh_node.keystore.enclave.verify_enclave_attestation(event)[source]

Verify the hardware enclave attestation tag of a Nostr event.

Parameters:

event (NostrEvent | Mapping[str, Any])

Return type:

tuple[bool, str]

fleetmesh_node.keystore.enclave.verify_signature(message, multikey_str, signature_bytes)[source]

Verify an arbitrary message signature against an enclave multikey.

Parameters:
Return type:

tuple[bool, str]

fleetmesh_node.keystore.enclave.verify_detached_attestation(event_id, multikey_str, signature_hex, hardware_tier='hardware-enclave')[source]

Verify a detached hardware attestation receipt over an event ID.

Parameters:
  • event_id (str)

  • multikey_str (str)

  • signature_hex (str)

  • hardware_tier (str)

Return type:

tuple[bool, str]