3. Identity & Addressing (fleetmesh_core.identity)
The fleetmesh_core.identity package implements Decentralized Identifiers (DIDs),
content addressing identifiers (CIDs), DIDComm message envelopes, and multi-protocol
origin mapping.
3.1. Identity Subsystem
Node identity: blinded identifiers, and what makes a descriptor valid.
Every label comes from schema/constants.json and every tag rule from schema/kinds.json, so this module cannot disagree with the protocol version digest. If it does, check-package.py or check-registry.py has already failed.
- fleetmesh_core.identity.identity.protocol_version(identifier)[source]
FLEETMESH + ‘sync/1.2’ -> (‘sync’, 1, 2); None if it is not shaped so.
- fleetmesh_core.identity.identity.floor_of(name, major)[source]
The lowest minor of <name>/<major> this node still talks to.
The protocols two nodes can run with each other, one identifier each.
Exact guarantee: for every (name, major) that both sides declare, where the peer’s minor is at or above our floor for that name/major, the result holds FLEETMESH + name/major.min(our minor, peer minor) - the highest version both are known to read, since minors are additive. If either side declares the same name/major more than once the lowest of each side’s minors is what is compared. Different majors never match, and nothing in the result is an identifier neither side declared.
Callers that want “is name/major shared” rather than the exact identifier compare on protocol_version()[:2]; see compatible().
The (name, major) pairs shared_protocols() would return an identifier for.
- fleetmesh_core.identity.identity.compatible(theirs, ours=None)[source]
Why a peer’s protocol declaration cannot peer with ours; empty means it can.
Only the required protocols decide this. Everything else is shared or not, which is a subsystem’s business, not the peering’s.
- fleetmesh_core.identity.identity.notices(event, digest=None)[source]
What is worth telling an operator about a peer’s descriptor without refusing it: a different schema digest (provenance, since 0.3), and protocols this build does not define (a newer peer, most likely).
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
digest (str | None)
- Return type:
- fleetmesh_core.identity.identity.grant_tag(sk_hex, counterparty_pk_hex)[source]
The d tag of a kind 30801. Both parties derive it; nobody else can.
- fleetmesh_core.identity.identity.job_tag(sk_hex, counterparty_pk_hex)[source]
The d tag of a kind 30811. Same construction, different labels.
- fleetmesh_core.identity.identity.first(event, name, default=None)[source]
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
name (str)
- Return type:
- fleetmesh_core.identity.identity.protocols_of(event)[source]
The fleetmesh protocols a descriptor declares: every c tag whose value is a protocol identifier. Plain capabilities (relay, blossom, mediator) are hints and are not returned; these are binding.
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.identity.identity.foreign_protocols_of(event)[source]
Protocol identifiers a descriptor declares under an origin that is not fleetmesh’s: every https:// c tag shaped <origin>/<name>/<major>.<minor> that protocols_of() leaves out.
These are dialects - protocols minted by someone else, under their own origin, which fleetmesh relays and never judges. They take no part in peering admission (only the required fleetmesh protocols do), are not governed by the schema digest, and need no registry entry here: the origin is the namespace. A node that speaks one says so with the same tag it uses for ours; one that does not ignores it.
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.identity.identity.validate_descriptor(event, now, digest=None)[source]
Check a kind 11801 against every rule the specification states.
Returns a list of failures; empty means valid. Deliberately returns all of them rather than raising on the first, because an operator fixing a descriptor wants the whole list.
now is the caller’s clock, always: this library never reads the wall clock, so a verdict about expiry is reproducible from its inputs alone.
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
now (int)
digest (str | None)
- Return type:
- fleetmesh_core.identity.identity.pow_bits(event_id_hex)[source]
Leading zero bits of an event id, for NIP-13.
The id must be exactly 64 hex digits; anything else raises ValueError. int(s, 16) alone accepted an eight-character string and counted the 224 bits it did not have as leading zeros, which is a proof of work for free.
3.2. Decentralized Identifiers (DID)
DIDs: did:nostr is the identity; did:key and did:peer are derived views of it.
A node IS its did:nostr - the subject is the secp256k1 x-only pubkey that signs every event. did:key and did:peer are deterministic re-encodings of the keys the descriptor already carries, so off-the-shelf DIDComm and VC tooling can address a node without a did:nostr resolver (constants.json#did, profile did-aliases). Neither adds a key, a curve or a trust root.
- did:key did:key:z<base58btc(multicodec || raw key)>; one per key kind.
The node key is secp256k1-pub (0xe7 0x01) over the COMPRESSED point (02 || x, even y as BIP-340 implies), the agreement key is x25519-pub (0xec 0x01), the transport key ed25519-pub (0xed 0x01).
- did:peer numalgo 2 (did:peer:2.<V|E|S elements>): the authentication key
as V, the agreement key as E, the DIDCommMessaging service as S with the spec’s abbreviations, base64url-nopad JSON. It is a SNAPSHOT of the descriptor: it changes when the endpoint or a key does. The descriptor is the source of truth; the did:peer is how that truth is spelt to a DIDComm library.
Standard library only; the point math is fleetmesh_core/crypto/crypto’s.
- class fleetmesh_core.identity.did.Service[source]
Bases:
TypedDict- serviceEndpoint: ServiceEndpoint
- class fleetmesh_core.identity.did.Document
Bases:
TypedDict- verificationMethod: list[VerificationMethod]
- fleetmesh_core.identity.did.compressed_node_key(x_only_hex)[source]
02 || x: the even-y point BIP-340 x-only keys stand for.
- fleetmesh_core.identity.did.parse_did_key(did)[source]
(kind, raw bytes) of a did:key this profile emits; refuses other codecs.
- fleetmesh_core.identity.did.did_peer(node_pk_hex, agreement_raw, service)[source]
did:peer:2 of a node: V = the node key, E = the agreement key, S = the DIDComm service.
- fleetmesh_core.identity.did.parse_did_peer(did)[source]
{node: x-only hex, agreement: hex or None, service: expanded or None}.
- fleetmesh_core.identity.did.parse(did)[source]
{method, node} for any DID this profile speaks; node is the x-only hex when it names one.
- fleetmesh_core.identity.did.did_nostr(pubkey)[source]
Format an x-only hex pubkey as did:nostr:<pubkey>.
- fleetmesh_core.identity.did.node_of_did(did_or_kid)[source]
Extract canonical 64-hex node pubkey from did:nostr, did:key, or did:peer identifier/KID.
- fleetmesh_core.identity.did.document(desc)[source]
The node profile a did:nostr resolver emits for a kind 11801, with its aliases.
- fleetmesh_core.identity.did.signing_key(did)[source]
(curve, raw public key) a DID can verify a signature with, or None.
An x25519 agreement key is not a signing key and comes back None rather than being checked against the wrong algorithm.
- fleetmesh_core.identity.did.verify(did, msg32, sig_hex)[source]
Whether sig_hex is this DID’s signature over msg32.
False rather than raising, for every reason: a malformed DID, a method this profile does not speak, an agreement key offered as a signing key, a bad signature. A verifier on an audit path that can raise is a verifier that can be made to fail closed by a malformed input, and the caller needs an answer, not an exception.
- fleetmesh_core.identity.did.self_certifying(did)[source]
Whether this DID can be verified from the identifier alone.
- fleetmesh_core.identity.did.resolvable(did)[source]
Whether verifying this DID would need a document fetched.
- fleetmesh_core.identity.did.refusal(did)[source]
Why this DID cannot verify a signature, in a sentence.
- fleetmesh_core.identity.did.parse_operator(value)[source]
The operator an operator tag names. Bare 64-hex and did:nostr:<hex> are the same operator and compare equal here because both come back as the parsed pubkey; did:group:<slug> parses with a refusal that says why nothing verifies under it yet. Anything else is a ValueError.
3.3. DIDComm Envelopes
DIDComm v2 encrypted envelopes: ECDH-1PU authcrypt and ECDH-ES anoncrypt.
Everything two nodes say privately is DIDComm v2. constants.json names the agreement as “ECDH-ES and ECDH-1PU as DIDComm v2 defines them” over X25519, so this module is those two constructions and nothing else:
- authcrypt alg ECDH-1PU+A256KW, enc A256CBC-HS512. The sender’s static key
is in the agreement, so the recipient knows who wrote it. Every message after first contact.
- anoncrypt alg ECDH-ES+A256KW, enc A256CBC-HS512. First contact only,
before the peer has any reason to reveal itself.
JWE JSON serialisation, general form, one or more recipients. The Concat KDF is NIST SP 800-56A one-step with SHA-256 as RFC 7518 uses it; ECDH-1PU adds the sender’s static agreement to Z and, in key-wrapping mode, the content tag to the KDF input so a recipient cannot re-target the message. Pinned in node/tests/test_crypto.py to draft-madden-jose-ecdh-1pu-04 Appendix B, RFC 7518 Appendix C and RFC 3394.
- class fleetmesh_core.identity.didcomm.JWERecipient[source]
Bases:
TypedDict- header: JWERecipientHeader
- exception fleetmesh_core.identity.didcomm.EnvelopeError[source]
Bases:
FleetmeshError,ValueError
- fleetmesh_core.identity.didcomm.concat_kdf(z, alg, apu, apv, keydatalen_bits, cctag=None)[source]
NIST SP 800-56A one-step KDF, SHA-256, one round (every key here is <= 256 bits).
FixedInfo = AlgorithmID || PartyUInfo || PartyVInfo || SuppPubInfo, each length-prefixed; SuppPubInfo is keydatalen and, for ECDH-1PU key wrap, the length-prefixed content tag.
- fleetmesh_core.identity.didcomm.cbc_hs512_encrypt(cek, iv, plaintext, aad)[source]
RFC 7518 5.2.5. cek is 64 bytes: MAC key first, then the AES key.
- fleetmesh_core.identity.didcomm.kek_1pu(alg, ze, zs, apu, apv, tag)[source]
ECDH-1PU key-wrapping KEK: Z = Ze || Zs, tag in the KDF.
- fleetmesh_core.identity.didcomm.apv_for(recipient_kids)[source]
DIDComm v2: base64url(SHA-256 of the sorted recipient kids joined by ‘.’).
- fleetmesh_core.identity.didcomm.encrypt(plaintext_message, recipients, sender=None, eph_seed=None, cek=None, iv=None)[source]
A JWE for one plaintext message.
recipients: [(kid, X25519PublicKey)]. sender: (skid, X25519PrivateKey) for authcrypt, None for anoncrypt. The seed, CEK and IV parameters exist for the vectors; a node never passes them.
- fleetmesh_core.identity.didcomm.decrypt(jwe, my_kid, my_priv, resolve_sender=None)[source]
Open a JWE addressed to my_kid. For authcrypt, resolve_sender(skid) must return the sender’s static X25519 public key; the sender is then authenticated by the agreement itself. Returns (message, skid or None).
3.4. Content Identifiers (CID)
IPFS CIDv1 multibase ‘b’ (raw sha2-256 and dag-cbor) codec.
Standard library only. All identifiers here use canonical multibase ‘b’ (lowercase Base32, RFC 4648 without padding), multicodec 0x55 (raw) or 0x71 (dag-cbor), and sha2-256 multihash (0x12, length 0x20).
- exception fleetmesh_core.identity.cid.CIDError[source]
Bases:
ValueErrorRaised when a CID cannot be parsed or violates canonical CIDv1 constraints.
- class fleetmesh_core.identity.cid.CIDLink[source]
Bases:
objectAn IPLD Link (CID) represented as Tag 42 in DAG-CBOR and bafy…/bafk… string.
Supports CIDv1 with raw (0x55) or dag-cbor (0x71) multicodec and sha2-256 multihash.
- to_cbor_tag_bytes()[source]
Produce the byte string value for CBOR Tag 42 (prefixed with null multibase byte).
- Return type:
- classmethod from_cbor_tag_bytes(data)[source]
Parse from CBOR Tag 42 byte payload (stripping 0x00 multibase prefix).
- classmethod from_sha256(sha256_hex_or_bytes, codec=113)[source]
Construct CIDLink from SHA-256 hash.
- fleetmesh_core.identity.cid.sha256_to_cid(sha256_hex)[source]
Map SHA-256 hex digest to standard IPFS CIDv1 multibase ‘b’ (raw sha2-256).
CIDv1 format: - 0x01: CIDv1 - 0x55: raw codec (varint 0x55) - 0x12: sha2-256 multihash function - 0x20: 32 bytes digest length - raw 32-byte SHA-256 digest Encoded in lowercase RFC 4648 Base32 with ‘b’ multibase prefix. Produces canonical ‘bafkrei…’ prefix.
3.5. Iroh Tickets
The iroh rung’s identity on the wire: its ALPN and its NodeAddr ticket.
Standard library only, no external dependencies. Used across transport adapters, sidecars, and routers to identify an Iroh endpoint.
- class fleetmesh_core.identity.iroh_ticket.IrohTicket[source]
Bases:
objectAn Iroh NodeAddr ticket identifying an Iroh endpoint.
Contains: - node_id: Hex-encoded 32-byte Ed25519 transport key (iroh NodeId) - host: Direct IP or hostname - port: Direct listen port - relay_url: Optional DERP / home relay URL
3.6. Origin Validation & Multi-Keys
The one rule about identifier origins.
A capability or protocol identifier is https://<origin>/<name>/<major>.<minor>. The Fleetmesh origin (the one every PIURI in schema/messages.json shares) is RESERVED: identifiers under it are governed by the schema digest, so nothing registered at runtime – a plugin’s wire protocol, a sidecar manifest, an operator config entry – may claim one. Everyone else uses their own origin.
This module is a leaf: standard library only, zero dependencies.
- fleetmesh_core.identity.origin.origin_of(identifier)[source]
https://<host>/grasp/1.0 -> https://<host>/.
Scheme and host via urllib.parse, not a character-wise prefix: a prefix every identifier shares by accident would refuse one of our own protocols added later and admit a lookalike host as foreign. ValueError when the identifier is not https://<host>/…
- fleetmesh_core.identity.origin.reserved(identifier, origin)[source]
True when identifier lives under the reserved origin.
Compared origin-to-origin after normalisation, never by string prefix, so a lookalike host that merely starts with ours is foreign and a trailing-slash difference is not a loophole.
3.7. Relay Lists
Kind 10050: where a peer wants its gift wraps delivered (NIP-17).
A node that must reach a peer that is not listening publishes a kind 1059 to relays the peer will read later. Which relays those are is the peer’s to say, and NIP-17 is where it says it: a replaceable kind 10050 with one relay tag per URL. This module reads that event and nothing else; the node decides what to do when a peer has none (the node’s own relays, as before this module existed).
Reused, not invented: the shape is NIP-17’s. What fleetmesh adds is the rule in docs/implementing.md that a stored wrap goes to these relays when the peer has published them - and that every node publishes one. The relay rung is the floor of the transport ladder, the one way a node can always be reached; a kind 10050 is where that floor is stated, in the place any Nostr client already looks. build is the writing half: the tags a node publishes, which dm_relays reads back unchanged.
- fleetmesh_core.identity.relaylist.dm_relays(ev)[source]
The relay URLs a kind 10050 names, in the order given, deduplicated, anything that is not a ws(s) URL dropped, capped at MAX_RELAYS. An event of another kind yields nothing: the caller asked the wrong question and gets no relays rather than a wrong answer.
- Parameters:
ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.identity.relaylist.build(relays)[source]
The tags of the kind 10050 a node publishes for its own inbox: one relay tag per URL, in the order given, deduplicated, anything that is not a ws(s) URL refused rather than dropped (a node that would publish a non-relay as its inbox has a config error, not a wire condition), capped at MAX_RELAYS. dm_relays(build(x)) == x for any valid x.
3.8. ATProto Identity (did:plc & did:web)
AT Protocol (atproto) identity, handle resolution, and K-256 cryptography.
Standard library only. Implements: - did:plc directory resolution (https://plc.example.org/{did}) - did:web resolution (https://{domain}/.well-known/did.json) - Handle resolution via DNS TXT (_atproto.{handle}) and HTTPS (/.well-known/atproto-did) - Bidirectional handle verification (handle -> DID and DID doc alsoKnownAs -> handle) - K-256 (secp256k1) deterministic ECDSA (RFC 6979) signing and verification - Conversion between Fleetmesh secp256k1 keys and ATProto did:key:zQ3sh… - AtprotoIdentityAdapter conforming to ProtocolIdentityAdapter
- exception fleetmesh_core.identity.atproto.AtprotoError[source]
Bases:
FleetmeshErrorBase error for ATProto identity operations.
- exception fleetmesh_core.identity.atproto.DIDResolutionError[source]
Bases:
AtprotoErrorRaised when a DID cannot be resolved or document is invalid.
- exception fleetmesh_core.identity.atproto.HandleResolutionError[source]
Bases:
AtprotoErrorRaised when a handle cannot be resolved or is invalid.
- class fleetmesh_core.identity.atproto.AtprotoResolver[source]
Bases:
objectResolves and caches ATProto DIDs (did:plc, did:web) and handles.
- __init__(plc_directory='https://plc.example.org', cache_ttl=300.0, fetcher=None, dns_resolver=None, dns_txt=None)[source]
- resolve_handle_http(handle)[source]
Resolve handle via HTTPS GET https://<handle>/.well-known/atproto-did.
- resolve_handle(handle)[source]
Resolve handle to DID trying DNS TXT first, then HTTPS well-known fallback.
- verify_handle(handle, did)[source]
Bidirectionally verify that handle resolves to DID and DID doc claims handle.
- static get_signing_key(doc)[source]
Extract public key multibase string (or did:key) from DID document.
- static get_pds_endpoint(doc)[source]
Extract AtprotoPersonalDataServer endpoint URI from DID document.
- class fleetmesh_core.identity.atproto.AtprotoIdentityAdapter[source]
Bases:
objectTranslates between Fleetmesh keys and ATProto DIDs / handles.
- __init__(keystore=None, resolver=None, handle=None, did=None)[source]
- Parameters:
keystore (Any)
resolver (AtprotoResolver | None)
handle (str | None)
did (str | None)
- fleetmesh_core.identity.atproto.is_valid_did(did)[source]
True if string is a valid ATProto did:plc, did:web, or did:key.
- fleetmesh_core.identity.atproto.is_valid_handle(handle)[source]
True if string conforms to ATProto handle domain name syntax.
- fleetmesh_core.identity.atproto.parse_at_uri(uri)[source]
Parse an at:// URI into (did_or_handle, collection, rkey).
- Example: at://alice.bsky.social/app.bsky.feed.post/3k23v5w6 ->
(‘alice.bsky.social’, ‘app.bsky.feed.post’, ‘3k23v5w6’)
- fleetmesh_core.identity.atproto.node_pk_to_did_key(x_only_hex_or_bytes)[source]
Map a 32-byte secp256k1 public key to ATProto did:key:zQ3sh… string.
- fleetmesh_core.identity.atproto.did_key_to_public_key_bytes(did_key_str)[source]
Extract compressed 33-byte public key from did:key:zQ3sh…
- fleetmesh_core.identity.atproto.ecdsa_sign(msg_bytes, sk_hex, normalize_even_y=True)[source]
Sign msg_bytes with secp256k1 private key using deterministic RFC 6979 ECDSA.
Returns raw 64-byte r || s signature with low-S normalization per BIP-62 / ATProto. If normalize_even_y is True, normalizes scalar to even-y matching compressed_node_key.