TypeScript

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

It is designed to guide TypeScript developers through installing, understanding, and integrating the DeRec protocol using the official TypeScript SDKs for Node.js and the Web.

---

TypeScript SDK Overview

The DeRec TypeScript SDK provides a managed surface over the same DeRecProtocol orchestrator the Rust SDK exposes. Internally each package wraps the WASM compilation of the Rust derec-library crate — the WASM blob, the JS glue, and the bigint/Uint8Array marshalling are all internal details. TypeScript consumers see a managed DeRecProtocol class, async/await methods, typed DeRecEvent objects, and a thrown DeRecError shape.

The SDK ships as two packages with the same API surface:

Package	Runtime
@derec-alliance/nodejs	Node.js
@derec-alliance/web	Browsers (and other ESM environments that can load a .wasm blob)

Both packages expose the same TypeScript types (DeRecProtocol, DeRecProtocolBuilder, DeRecEvent, ContactMode, SenderKind, FlowKind, the four store interfaces, Transport, …) declared in their index.d.ts. Pick the package that matches your runtime; every code sample in the rest of this section works against either one.

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

---

Installation

Both packages publish at the same version as the derec-library Rust crate they wrap.

Node.js

npm install @derec-alliance/nodejs@0.0.1-alpha.7
# or: yarn add @derec-alliance/nodejs@0.0.1-alpha.7
# or: pnpm add @derec-alliance/nodejs@0.0.1-alpha.7

The Node package loads its WASM blob synchronously on import — no initialization step is required.

import { DeRecProtocolBuilder, FlowKind, SenderKind } from "@derec-alliance/nodejs";

Browser

npm install @derec-alliance/web@0.0.1-alpha.7

The Web package ships the WASM blob as a separate asset and exposes an init() function that must be awaited before any other API is used. The exact wiring depends on the bundler.

import { init, DeRecProtocolBuilder, FlowKind, SenderKind } from "@derec-alliance/web";

await init();
// API ready — every other call below is identical to the Node package.

Vite, Webpack, and Rollup all need to be told how to resolve and serve the .wasm asset alongside the JS bundle — consult the bundler's documentation on bundling WebAssembly modules.

Both packages are pre-1.0. Breaking changes between alpha versions are expected — pin an exact version ("@derec-alliance/nodejs": "0.0.1-alpha.7") in your package.json and treat upgrades as a deliberate review step.

---

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(...).

import {
  DeRecProtocolBuilder,
  FlowKind,
  SenderKind,
  type ChannelStore,
  type DeRecEvent,
  type SecretStore,
  type ShareStore,
  type Transport,
  type UserSecretStore,
} from "@derec-alliance/nodejs";

// 1. Application-supplied persistence + transport. The package ships no
//    default implementation — your app owns storage and network I/O.
const channels: ChannelStore = new MyChannelStore();
const shares: ShareStore = new MyShareStore();
const secrets: SecretStore = new MySecretStore();
const userSecrets: UserSecretStore = new MyUserSecretStore();
const transport: Transport = new MyTransport();
// transport.send(endpoint, message) ships outbound bytes for the library.

// 2. Build the orchestrator. One DeRecProtocol instance manages one Secret.
const protocol = new DeRecProtocolBuilder(0xC0FFEEn)        // secretId: bigint
  .withChannelStore(channels)
  .withShareStore(shares)
  .withSecretStore(secrets)
  .withUserSecretStore(userSecrets)
  .withTransport(transport)
  .withOwnTransport({ uri: "https://owner.example.com", protocol: "https" })
  .withThreshold(3)
  .build();

// 3. Drive an inbound envelope through the orchestrator. The library
//    returns every DeRecEvent it produced while handling the envelope.
const envelope: Uint8Array = await receiveFromTransport();
const events: DeRecEvent[] = await protocol.process(envelope);

for (const event of events) {
  switch (event.type) {
    case "PairingCompleted":
      console.log(`paired channel ${event.channel_id} as ${SenderKind[event.kind]}`);
      break;
    case "ActionRequired":
      // App consents; library resumes the flow and emits its own events.
      const followUp = await protocol.accept(event.action);
      break;
    case "ShareStored":
      console.log(`stored share v${event.version} for ${event.channel_id}`);
      break;
    case "SecretRecovered":
      useRecoveredBytes(event.secret);
      break;
  }
}

The builder requires withChannelStore, withShareStore, withSecretStore, withTransport, and withOwnTransport — calling build() without all five throws. Optional setters (withThreshold, withKeepVersionsCount, withTimeout, withCommunicationInfo, withAutoRespondOnFailure, withUnpairAck, withAutoReplyTo, withReplicaId) tune flow behaviour and replica participation.

Every code sample in this section uses @derec-alliance/nodejs for brevity. Swap the import for @derec-alliance/web and add a top-level await init(); and the rest of the code is identical — the two packages expose the same DeRecProtocol / DeRecProtocolBuilder / DeRecEvent surface.

---

Protocol Flows

The SDK exposes every DeRec flow through a single protocol.start(flowKind, params) entry point plus the inbound process / accept 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 protocol.start(FlowKind.X, params); the library produces outbound envelopes through your Transport.send; the responder feeds inbound envelopes to protocol.process and consents to any { type: "ActionRequired" } event via protocol.accept(action).

---

Message Model

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

• Inbound and outbound envelopes are plain Uint8Array buffers 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, .NET, and other SDKs

• Clear separation between protocol and transport layers

Applications are responsible for:

• Delivering outbound Uint8Array envelopes — the library passes them to Transport.send({ uri, protocol }, message) — to the counterparty

• Receiving inbound Uint8Array envelopes and passing them back through DeRecProtocol.process(...)

Numeric ids that come from the protocol (channelId, secretId, replicaId) are bigint on the input side because the wire format uses u64. On event objects they are surfaced as decimal strings so JSON-serializable consumers can carry them across messaging boundaries without precision loss.

---

Error Handling

All library-side errors surface as a thrown DeRecError:

import { type DeRecError } from "@derec-alliance/nodejs";

try {
  await protocol.process(envelope);
} catch (err) {
  const e = err as DeRecError;
  // e.category — "pairing" | "sharing" | "recovery" | "verification" | ...
  // e.code     — "DEREC_ERROR" or a specific protocol code
  // e.message  — human-readable detail
  // e.status / e.memo       — populated when the peer answered with a non-Ok status
  // e.expected / e.got      — populated for version-mismatch failures
  console.error(`${e.category}/${e.code}: ${e.message}`);
}

DeRecError.category identifies which protocol phase produced the error ("pairing", "sharing", "recovery", "verification", "discovery", "unpairing", "secret_store", "channel_store", "share_store", "invariant", "input", "wasm", ...). The same (category, code) pair carries the same meaning across every language binding — see Error Handling for the cross-binding catalog.

---

API Reference

Each package ships its index.d.ts alongside the JavaScript so editors and type-checkers surface the full surface natively. The published types are the authoritative reference for every method, parameter, and DeRecEvent variant documented in this section.

Recommended documentation structure:

• README.md

• pairing.md

• share-distribution.md

• verification.md

• recovery.md

---

SDK Architecture

The TypeScript packages provide the managed DeRecProtocol orchestrator surface — turning the WASM-exported functions into typed async methods, marshalling Uint8Array / bigint across the JS/WASM boundary, and shaping events into the DeRecEvent union. The WASM blob is the same compiled derec-library crate the Rust SDK consumes directly. Every binding is a thin translation over the same core.