.Net

This document provides the recommended structure and content for the .NET SDK section of the DeRec documentation.

It is designed to guide .NET developers through installing, understanding, and integrating the DeRec protocol using the official DeRec.Library NuGet package.

---

.NET SDK Overview

The DeRec .NET SDK provides a managed surface over the same DeRecProtocol orchestrator the Rust SDK exposes.

The SDK allows applications to:

• Distribute Secret shares across trusted Helpers using a threshold secret-sharing scheme

• Verify Helpers still hold shares

• Recover the Secret from a threshold of Helpers

• Optionally extend the Owner identity across multiple devices via the replica feature, with automatic Secret synchronization between them

The SDK is published as a single NuGet package:

DeRec.Library

Internally the package is built on top of the C ABI exposed by the Rust derec-library crate. The FFI bridge, the pinned managed delegates, and the native handle lifecycle are all internal — the .NET consumer sees a managed DeRec.Library.Orchestrator.DeRecProtocol class, async methods, typed exceptions, and IDisposable lifetime management.

---

Installation

Add the SDK to your project:

dotnet add package DeRec.Library --version 0.0.1-alpha.7

The SDK is pre-1.0. Breaking changes between alpha versions are expected — pin an exact version in your project file and treat upgrades as a deliberate review step.

The package ships pre-built native binaries (libderec_library.dylib / .so / .dll) for the supported runtime identifiers (osx-arm64, osx-x64, linux-x64, linux-arm64). NuGet's RID-resolution picks the correct one at build time.

---

Quick Start

Implement the four store interfaces, a transport callback, and drive the orchestrator. The example below is the minimum scaffold; the four flow chapters show how each protocol round-trip flows through process(...).

using DeRec.Library;
using DeRec.Library.Orchestrator;
using DeRec.Library.Primitives;

// 1. Application-supplied persistence + transport. The package ships no
//    default implementation — your app owns storage and network I/O.
IChannelStore channels = new MyChannelStore();
IShareStore shares = new MyShareStore();
ISecretStore secrets = new MySecretStore();
IUserSecretStore userSecrets = new MyUserSecretStore();
ITransport transport = new MyTransport(); // void Send(uri, protocol, bytes)

// 2. Build the orchestrator. One DeRecProtocol instance manages one Secret.
using var protocol = new DeRecProtocolBuilder(secretId: 0xC0FFEEUL)
    .WithChannelStore(channels)
    .WithShareStore(shares)
    .WithSecretStore(secrets)
    .WithUserSecretStore(userSecrets)
    .WithTransport(transport)
    .WithOwnTransport(new TransportProtocol("https://owner.example.com"))
    .WithThreshold(3)
    .Build();

// 3. Drive an inbound envelope through the orchestrator. The library
//    emits every DeRecEvent it produced while handling the envelope.
byte[] envelope = ReceiveFromTransport();
IReadOnlyList<DeRecEvent> events = await protocol.ProcessAsync(envelope);

foreach (var ev in events)
{
    switch (ev)
    {
        case PairingCompletedEvent paired:
            Console.WriteLine($"paired channel {paired.ChannelId} as {paired.Kind}");
            break;
        case ActionRequiredEvent action:
            // App consents; library resumes the flow and emits its own events.
            await protocol.AcceptAsync(action.Action);
            break;
        case ShareStoredEvent stored:
            Console.WriteLine($"stored share v{stored.Version} for {stored.ChannelId}");
            break;
        case SecretRecoveredEvent recovered:
            UseRecoveredBytes(recovered.Secret);
            break;
    }
}

DeRecProtocol is IDisposable — the instance owns the native handle plus a set of pinned delegates, and Dispose() releases both. Wrap it in a using block (or hold it on a long-lived service and dispose at shutdown).

---

Protocol Flows

The SDK exposes every DeRec flow through a single protocol.StartAsync(FlowKind, ...) entry point plus the inbound ProcessAsync / AcceptAsync loop. The four chapters below cover the core integration areas; the full flow catalog (Discovery, Unpair, UpdateChannelInfo) lives in Protocol Specification / Flows.

Flow	Purpose
Pairing	Establish secure communication between two participants — Owner ↔ Helper, or Replica pairings
Share Distribution	Split the Secret and distribute shares to Helpers; sync the full Secret to every paired Replica
Verification	Verify Helpers still hold shares
Recovery	Recover shares and reconstruct the Secret

Each flow follows the same shape: the initiator calls StartAsync(FlowKind.X, params); the library produces outbound envelopes through your ITransport; the responder feeds inbound envelopes to ProcessAsync and consents to any ActionRequiredEvent via AcceptAsync.

---

Message Model

The SDK operates on serialized protocol envelopes rather than exposing protobuf types directly.

• Inbound and outbound envelopes are plain byte[] arrays on both sides of the orchestrator

• These bytes represent:

  • A serialized DeRecMessage envelope, or

  • A plain serialized ContactMessage (the out-of-band bootstrap, see Pairing)

• For encrypted protocol exchanges, the DeRecMessage envelope contains an encrypted inner protobuf message — the library performs the encryption, decryption, and framing for you

This design ensures:

• Transport-agnostic usage (HTTP, WebSocket, mailbox relay, etc.)

• Language-agnostic interoperability with the Rust, TypeScript, and other SDKs

• Clear separation between protocol and transport layers

Applications are responsible for:

• Delivering outbound byte[] envelopes — the library passes them to ITransport.Send(uri, protocol, message) — to the counterparty

• Receiving inbound byte[] envelopes and passing them back through DeRecProtocol.ProcessAsync(...)

---

Error Handling

All library-side errors surface as the typed DeRec.Library.DeRecException:

try
{
    await protocol.ProcessAsync(envelope);
}
catch (DeRecException ex)
{
    // ex.Category — DeRecCategory.* (Pairing, Sharing, Recovery, ...)
    // ex.Code     — DeRecCode.* (ReplicaIdNotConfigured, MissingSharedKey, ...)
    // ex.Message  — human-readable detail
    // ex.PeerStatus / ex.PeerMemo — populated for NonOkStatus
    // ex.Expected / ex.Got       — populated for VersionMismatch
    Console.Error.WriteLine(ex);
}

DeRecException.Category mirrors the FFI's DEREC_CATEGORY_* constants and identifies which protocol phase produced the error (Pairing, Sharing, Recovery, Verification, Discovery, Unpairing, SecretStore, ChannelStore, ShareStore, Invariant, InvalidInput, ...). DeRecException.Code mirrors the DEREC_CODE_* constants and identifies the specific reason — for example DeRecCode.ReplicaIdNotConfigured when a replica-mode flow is started without WithReplicaId(...).

The same (Category, Code) pair carries the same meaning across every language binding.

---

API Reference

The package surfaces XML doc comments on every public type. Full API documentation lives in the GitHub repository under packages/dotnet/DeRec.Library/src/.

Recommended documentation structure:

• README.md

• pairing.md

• share-distribution.md

• verification.md

• recovery.md

---

SDK Architecture

DeRec.Library provides the managed DeRecProtocol orchestrator surface and the bridging delegates that satisfy the Rust-side store and transport traits. The native derec-library crate is the source of truth for protocol logic — every binding is a thin translation over the same core.