ma_core/
lib.rs

1//! # ma-core
2//!
3//! A lean `DIDComm` service library for the ma ecosystem.
4//!
5//! `ma-core` provides the building blocks for ma-capable endpoints:
6//!
7//! - **DID documents** — create, validate, resolve, and publish `did:ma:` documents
8//!   to IPFS/IPNS (via Kubo on native targets). Use [`MaExtension`] to build the
9//!   `ma:` extension field, and [`config::SecretBundle::build_document`] (`config`
10//!   feature) as the single entry point for a complete, signed document.
11//! - **Service inboxes** — bounded, TTL-aware FIFO queues ([`Inbox`])
12//!   for receiving validated messages on named protocol services.
13//! - **Outbound sending** — fire-and-forget delivery of validated [`Message`] objects
14//!   to remote endpoints, serialized to CBOR on the wire.
15//! - **Endpoint abstraction** — the [`MaEndpoint`] trait with pluggable
16//!   transport backends.
17//! - **Transport parsing** — extract endpoint IDs and protocols from DID document
18//!   service strings (`/iroh/<id>/<protocol>`).
19//! - **Identity bootstrap** — secure secret key generation and persistence.
20//!
21//! ## Services
22//!
23//! Every endpoint must provide `/ma/inbox/0.0.1` (the default inbox).
24//! Endpoints may optionally provide `ma/ipfs/0.0.1` to publish DID documents
25//! on behalf of others.
26//!
27//! ## Feature flags
28//!
29//! - **`kubo`** — enables native IPFS RPC backend for publishing (native only).
30//! - **`iroh`** — enables the internal iroh QUIC transport backend.
31//! - **`gossip`** — enables internal iroh-gossip broadcast support.
32//! - **`config`** — enables [`Config`], [`SecretBundle`], and [`MaArgs`] for
33//!   YAML-based daemon configuration, encrypted secret bundles, and CLI
34//!   argument parsing. Also provides [`config::SecretBundle::build_document`] and
35//!   [`config::SecretBundle::signing_key`] for constructing ready-to-publish DID documents.
36//!
37//! ## Platform support
38//!
39//! Core types (`Inbox`, `Service`, transport parsing, validation)
40//! compile on all targets including `wasm32-unknown-unknown`.
41//!
42//! ### wasm vs native
43//!
44//! - `ma-core` supports both wasm and native targets.
45//! - `IpfsGatewayResolver` (HTTP gateway DID fetch) is available on wasm and native.
46//! - Native IPFS RPC write/pin APIs are native-only (`not(wasm32)` + `kubo` feature).
47//! - wasm builds expose only `ipfs::gateway_resolver` (no native RPC helpers).
48//! - `config` serialization and `SecretBundle` crypto work on wasm.
49//! - `config` filesystem paths, CLI/env merging, and file I/O are native-only.
50//! - If your wasm application needs native IPFS RPC write/pin operations, provide
51//!   them in a native companion layer.
52
53#![forbid(unsafe_code)]
54#![allow(
55    clippy::cast_possible_truncation,
56    clippy::cast_precision_loss,
57    clippy::if_not_else,
58    clippy::items_after_statements,
59    clippy::manual_let_else,
60    clippy::map_unwrap_or,
61    clippy::missing_errors_doc,
62    clippy::must_use_candidate,
63    clippy::uninlined_format_args
64)]
65
66#[cfg(feature = "acl")]
67pub mod acl;
68#[cfg(feature = "config")]
69pub mod config;
70pub mod constants;
71pub mod did;
72pub mod doc;
73pub mod endpoint;
74pub mod error;
75pub mod identity;
76pub mod inbox;
77pub mod interfaces;
78pub mod ipfs;
79#[cfg(feature = "iroh")]
80#[allow(dead_code)]
81mod iroh;
82pub mod key;
83#[cfg(all(feature = "kubo", not(target_arch = "wasm32")))]
84mod kubo;
85pub mod msg;
86mod multiformat;
87#[cfg(feature = "iroh")]
88#[allow(dead_code)]
89mod outbox;
90pub mod service;
91pub mod topic;
92pub mod transport;
93pub(crate) mod ttl_queue;
94
95// ─── Re-export DID/message primitives ───────────────────────────────────────
96
97pub use did::{Did, DID_PREFIX};
98pub use doc::{
99    now_iso_utc, Document, MaExtension, Proof, VerificationMethod, DEFAULT_DID_CONTEXT,
100    DEFAULT_PROOF_PURPOSE, DEFAULT_PROOF_TYPE,
101};
102pub use error::{Error, MaError, Result};
103pub use identity::{
104    generate_identity, generate_identity_from_secret, ipns_from_secret, GeneratedIdentity,
105};
106pub use ipld_core::ipld::Ipld;
107pub use key::{
108    EncryptionKey, SigningKey, ASSERTION_METHOD_KEY_TYPE, ED25519_PUB_CODEC, EDDSA_SIG_CODEC,
109    KEY_AGREEMENT_KEY_TYPE, X25519_PUB_CODEC,
110};
111pub use msg::{
112    Envelope, Headers, Message, ReplayGuard, DEFAULT_MAX_CLOCK_SKEW_SECS, DEFAULT_MESSAGE_TTL_SECS,
113    DEFAULT_REPLAY_WINDOW_SECS, MESSAGE_PREFIX,
114};
115
116#[cfg(feature = "acl")]
117pub use acl::Acl;
118
119// ─── Re-export service constants ────────────────────────────────────────────
120
121pub use service::{
122    Service, BROADCAST_TOPIC, CONTENT_TYPE_BROADCAST, CONTENT_TYPE_DOC, CONTENT_TYPE_IPFS_REQUEST,
123    CONTENT_TYPE_MESSAGE, INBOX_PROTOCOL_ID, IPFS_PROTOCOL_ID, RPC_PROTOCOL_ID,
124};
125
126// ─── Re-export Inbox ────────────────────────────────────────────────────────
127
128pub use inbox::Inbox;
129
130// ─── Re-export Topic ────────────────────────────────────────────────────────
131
132pub use topic::{topic_id, Topic, TopicId};
133
134// ─── Re-export endpoint trait and implementations ───────────────────────────
135
136pub use endpoint::{MaEndpoint, DEFAULT_DELIVERY_PROTOCOL_ID};
137#[cfg(feature = "iroh")]
138pub use outbox::Outbox;
139
140/// Create a default ma endpoint backend from 32-byte secret key material.
141///
142/// This keeps the transport backend type internal while exposing
143/// [`MaEndpoint`] and [`Outbox`] as stable API surfaces.
144#[cfg(feature = "iroh")]
145pub async fn new_ma_endpoint(secret_bytes: [u8; 32]) -> Result<Box<dyn MaEndpoint>> {
146    let endpoint = iroh::new_endpoint(secret_bytes).await?;
147    Ok(Box::new(endpoint))
148}
149
150// ─── Re-export transport parsing ────────────────────────────────────────────
151
152pub use transport::{
153    endpoint_id_from_transport, endpoint_id_from_transport_value, normalize_endpoint_id,
154    protocol_from_transport, resolve_endpoint_for_protocol, resolve_inbox_endpoint_id,
155    transport_string,
156};
157
158// ─── Re-export identity helpers ─────────────────────────────────────────────
159
160pub use identity::{generate_secret_key_file, load_secret_key_bytes, socket_addr_to_multiaddr};
161
162// ─── Re-export config types ──────────────────────────────────────────────────
163
164#[cfg(all(feature = "config", not(target_arch = "wasm32")))]
165pub use config::MaArgs;
166#[cfg(feature = "config")]
167pub use config::{BrowserIdentityExport, Config, SecretBundle};
168
169// ─── Re-export DID resolution ───────────────────────────────────────────────
170
171pub use ipfs::gateway_resolver::{DidDocumentResolver, IpfsGatewayResolver};
172
173// ─── Re-export existing modules ─────────────────────────────────────────────
174
175pub use interfaces::{DidPublisher, IpfsPublisher};
176pub use ipfs::*;
ma_core/lib.rs

ma_core/
lib.rs
