---

Packages

filament
  |
  +-- pkg/trust       Device certificates, hardware keys, scoped tokens, signers, token exchange
  +-- pkg/session     Mesh session sharing, heartbeat monitoring, viewer connections
  +-- pkg/mcp         MCP transport normalization, server configs, mesh transport adapters
  +-- pkg/trace       W3C distributed tracing, baggage propagation, span context
  +-- pkg/telemetry   Node health checks, operations monitoring, uptime proofs
  |
  +-- internal/packet  Mesh packet framing (512-byte limit, flags, routing)
  +-- internal/quic    QUIC connection management

Each package is fully independent. Import any combination you need.

---

Quick Start

go get github.com/omxus/filament

Import individual packages:

import "github.com/omxus/filament/pkg/trust"
import "github.com/omxus/filament/pkg/session"
import "github.com/omxus/filament/pkg/mcp"
import "github.com/omxus/filament/pkg/trace"
import "github.com/omxus/filament/pkg/telemetry"

---

Package Overview

trust -- Device identity and credential management

Mutual TLS certificates, U2F/FIDO2 hardware key integration, scoped token exchange (RFC 8693), signer registries, and mesh token issuance.

mgr, _ := trust.NewCertManager(trust.DefaultConfig())
cert, _ := mgr.GenerateDeviceCert(ctx, "device-001")
tlsCfg, _ := mgr.GetTLSConfig("device-001")

session -- Mesh session lifecycle

Remote session meshification (shell detection + bootstrap injection), shared terminal sessions over gossip routing, heartbeat-based liveness monitoring, and viewer management.

hb := session.NewHeartbeatManager(session.HeartbeatConfig{
    Interval:  30 * time.Second,
    MaxMissed: 3,
    OnTimeout: func() { log.Println("connection lost") },
})
hb.Start(ctx)

mcp -- MCP protocol transport

Server name normalization, transport-agnostic MCP configs (stdio, SSE, HTTP, WebSocket, QUIC, BLE, Nostr), in-process and mesh transport implementations, and connection state management.

norm := mcp.NewNameNormalizer()
name := norm.NormalizeName("claude.ai My Server")
// => "claude_ai_My_Server"

client, server := mcp.CreateLinkedTransportPair()

trace -- Distributed tracing

W3C Trace Context propagation, trace state management, baggage (W3C spec), span lifecycle, binary-efficient AnyValue encoding for mesh packets, and context-aware span creation.

ctx, sc := trace.W3CStartSpan(ctx, "mesh.relay", true)
propagator := trace.NewW3CTraceContextPropagator()
propagator.Inject(ctx, carrier)

telemetry -- Node health and operations

Health status monitoring (BLE/QUIC/LoRa/Nostr connectivity), packet statistics, node registration with uptime proofs, epoch-based proof scheduling, and gossip-based status broadcasting.

hc := telemetry.NewHealthChecker("node-001")
hc.Start()
status := hc.CheckHealth()

---

Architecture

The packages compose naturally for mesh networking scenarios:

                     +-------------+
                     |   trust     |  Certificates, tokens, signers
                     +------+------+
                            |
                  +---------+---------+
                  |                   |
           +------+------+    +------+------+
           |   session   |    |    mcp      |  Sessions & MCP over mesh
           +------+------+    +------+------+
                  |                   |
                  +---------+---------+
                            |
                     +------+------+
                     |   trace     |  Propagated across all transports
                     +------+------+
                            |
                     +------+------+
                     |  telemetry  |  Monitors everything
                     +-------------+

trust issues device certificates and scoped tokens that session and mcp use for authenticated mesh communication. trace propagates context across all transports (BLE, QUIC, LoRa, Nostr). telemetry monitors node health and connectivity status across the mesh.

All packages share the internal packet layer for mesh framing.

---

Inspired By

• Google mTLS patterns -- Device certificate management, credential access boundaries, and token downscoping follow patterns from Google's production infrastructure
• OpenTelemetry W3C trace propagation -- The trace package implements the W3C Trace Context and Baggage specifications, adapted for mesh packet transport
• Mesh networking session management -- Session meshification, gossip-based routing, and heartbeat protocols drawn from real-world mesh network designs

---

License

MIT -- see LICENSE.