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

ma_core/
lib.rs
