cairn-ts 0.2.0

package/src/protocol/index.ts

@@ -0,0 +1,36 @@
+// Protocol module — CBOR envelope encode/decode, message types, version negotiation
+
+export type { MessageEnvelope } from './envelope.js';
+export { newMsgId, encodeEnvelope, encodeEnvelopeDeterministic, decodeEnvelope } from './envelope.js';
+
+export {
+  // Pairing
+  PAIR_REQUEST, PAIR_CHALLENGE, PAIR_RESPONSE, PAIR_CONFIRM, PAIR_REJECT, PAIR_REVOKE,
+  // Session
+  SESSION_RESUME, SESSION_RESUME_ACK, SESSION_EXPIRED, SESSION_CLOSE,
+  // Data
+  DATA_MESSAGE, DATA_ACK, DATA_NACK,
+  // Control
+  HEARTBEAT, HEARTBEAT_ACK, TRANSPORT_MIGRATE, TRANSPORT_MIGRATE_ACK,
+  // Mesh
+  ROUTE_REQUEST, ROUTE_RESPONSE, RELAY_DATA, RELAY_ACK,
+  // Rendezvous
+  RENDEZVOUS_PUBLISH, RENDEZVOUS_QUERY, RENDEZVOUS_RESPONSE,
+  // Forward
+  FORWARD_REQUEST, FORWARD_ACK, FORWARD_DELIVER, FORWARD_PURGE,
+  // Version
+  VERSION_NEGOTIATE,
+  // Ranges
+  CAIRN_RESERVED_START, CAIRN_RESERVED_END, APP_EXTENSION_START, APP_EXTENSION_END,
+  // Helpers
+  messageCategory, isApplicationType,
+} from './message-types.js';
+
+export type { VersionNegotiatePayload } from './version.js';
+export {
+  CURRENT_PROTOCOL_VERSION, SUPPORTED_VERSIONS,
+  selectVersion, createVersionNegotiate, parseVersionNegotiate, handleVersionNegotiate,
+} from './version.js';
+
+export type { CustomMessageCallback } from './custom-handler.js';
+export { CustomMessageRegistry } from './custom-handler.js';

package/src/protocol/message-types.ts

@@ -0,0 +1,74 @@
+// Pairing (0x01xx)
+export const PAIR_REQUEST = 0x0100;
+export const PAIR_CHALLENGE = 0x0101;
+export const PAIR_RESPONSE = 0x0102;
+export const PAIR_CONFIRM = 0x0103;
+export const PAIR_REJECT = 0x0104;
+export const PAIR_REVOKE = 0x0105;
+
+// Session (0x02xx)
+export const SESSION_RESUME = 0x0200;
+export const SESSION_RESUME_ACK = 0x0201;
+export const SESSION_EXPIRED = 0x0202;
+export const SESSION_CLOSE = 0x0203;
+
+// Data (0x03xx)
+export const DATA_MESSAGE = 0x0300;
+export const DATA_ACK = 0x0301;
+export const DATA_NACK = 0x0302;
+
+// Control (0x04xx)
+export const HEARTBEAT = 0x0400;
+export const HEARTBEAT_ACK = 0x0401;
+export const TRANSPORT_MIGRATE = 0x0402;
+export const TRANSPORT_MIGRATE_ACK = 0x0403;
+
+// Mesh (0x05xx)
+export const ROUTE_REQUEST = 0x0500;
+export const ROUTE_RESPONSE = 0x0501;
+export const RELAY_DATA = 0x0502;
+export const RELAY_ACK = 0x0503;
+
+// Rendezvous (0x06xx)
+export const RENDEZVOUS_PUBLISH = 0x0600;
+export const RENDEZVOUS_QUERY = 0x0601;
+export const RENDEZVOUS_RESPONSE = 0x0602;
+
+// Forward (0x07xx)
+export const FORWARD_REQUEST = 0x0700;
+export const FORWARD_ACK = 0x0701;
+export const FORWARD_DELIVER = 0x0702;
+export const FORWARD_PURGE = 0x0703;
+
+// Version negotiation
+export const VERSION_NEGOTIATE = 0x0001;
+
+// Reserved ranges
+export const CAIRN_RESERVED_START = 0x0100;
+export const CAIRN_RESERVED_END = 0xefff;
+export const APP_EXTENSION_START = 0xf000;
+export const APP_EXTENSION_END = 0xffff;
+
+/**
+ * Returns the category name for a given message type code.
+ */
+export function messageCategory(msgType: number): string {
+  if (msgType === 0x0001) return 'version';
+  if (msgType >= 0x0100 && msgType <= 0x01ff) return 'pairing';
+  if (msgType >= 0x0200 && msgType <= 0x02ff) return 'session';
+  if (msgType >= 0x0300 && msgType <= 0x03ff) return 'data';
+  if (msgType >= 0x0400 && msgType <= 0x04ff) return 'control';
+  if (msgType >= 0x0500 && msgType <= 0x05ff) return 'mesh';
+  if (msgType >= 0x0600 && msgType <= 0x06ff) return 'rendezvous';
+  if (msgType >= 0x0700 && msgType <= 0x07ff) return 'forward';
+  if (msgType >= 0x0800 && msgType <= 0xefff) return 'reserved';
+  if (msgType >= APP_EXTENSION_START && msgType <= APP_EXTENSION_END) return 'application';
+  return 'reserved';
+}
+
+/**
+ * Returns true if the given type code is in the application extension range.
+ */
+export function isApplicationType(msgType: number): boolean {
+  return msgType >= APP_EXTENSION_START && msgType <= APP_EXTENSION_END;
+}

package/src/protocol/version.ts

@@ -0,0 +1,98 @@
+import { encode, decode } from 'cborg';
+import { CairnError, VersionMismatchError } from '../errors.js';
+import { MessageEnvelope, newMsgId } from './envelope.js';
+import { VERSION_NEGOTIATE } from './message-types.js';
+
+/** Current protocol version. */
+export const CURRENT_PROTOCOL_VERSION = 1;
+
+/** All protocol versions this implementation supports, highest first. */
+export const SUPPORTED_VERSIONS: readonly number[] = [1];
+
+/** Payload for VersionNegotiate messages. */
+export interface VersionNegotiatePayload {
+  versions: number[];
+}
+
+/**
+ * Select the highest mutually supported version.
+ *
+ * Returns the selected version, or throws VersionMismatchError.
+ */
+export function selectVersion(ourVersions: readonly number[], peerVersions: number[]): number {
+  for (const v of ourVersions) {
+    if (peerVersions.includes(v)) {
+      return v;
+    }
+  }
+  throw new VersionMismatchError(
+    `no common protocol version: local supports [${ourVersions}], remote supports [${peerVersions}]`,
+    {
+      localVersions: [...ourVersions],
+      remoteVersions: [...peerVersions],
+      suggestion: 'update the peer with the older protocol version',
+    },
+  );
+}
+
+/** CBOR-encode a VersionNegotiatePayload. */
+function encodePayload(payload: VersionNegotiatePayload): Uint8Array {
+  try {
+    return encode(payload);
+  } catch (e) {
+    throw new CairnError('PROTOCOL', `CBOR payload encode error: ${e}`);
+  }
+}
+
+/** CBOR-decode a VersionNegotiatePayload. */
+function decodePayload(data: Uint8Array): VersionNegotiatePayload {
+  try {
+    return decode(data) as VersionNegotiatePayload;
+  } catch (e) {
+    throw new CairnError('PROTOCOL', `CBOR payload decode error: ${e}`);
+  }
+}
+
+/** Create a VersionNegotiate message envelope advertising our supported versions. */
+export function createVersionNegotiate(): MessageEnvelope {
+  const payload = encodePayload({ versions: [...SUPPORTED_VERSIONS] });
+  return {
+    version: CURRENT_PROTOCOL_VERSION,
+    type: VERSION_NEGOTIATE,
+    msgId: newMsgId(),
+    payload,
+  };
+}
+
+/** Parse a received VersionNegotiate envelope and extract the payload. */
+export function parseVersionNegotiate(envelope: MessageEnvelope): VersionNegotiatePayload {
+  if (envelope.type !== VERSION_NEGOTIATE) {
+    throw new CairnError(
+      'PROTOCOL',
+      `expected VERSION_NEGOTIATE (0x${VERSION_NEGOTIATE.toString(16).padStart(4, '0')}), got 0x${envelope.type.toString(16).padStart(4, '0')}`,
+    );
+  }
+  return decodePayload(envelope.payload);
+}
+
+/**
+ * Process a received VersionNegotiate and produce a response.
+ *
+ * Returns [selectedVersion, responseEnvelope]. If incompatible, throws VersionMismatchError.
+ */
+export function handleVersionNegotiate(
+  received: MessageEnvelope,
+): [number, MessageEnvelope] {
+  const peerPayload = parseVersionNegotiate(received);
+  const selected = selectVersion(SUPPORTED_VERSIONS, peerPayload.versions);
+
+  const responsePayload = encodePayload({ versions: [selected] });
+  const response: MessageEnvelope = {
+    version: CURRENT_PROTOCOL_VERSION,
+    type: VERSION_NEGOTIATE,
+    msgId: newMsgId(),
+    payload: responsePayload,
+  };
+
+  return [selected, response];
+}

package/src/server/index.ts

@@ -0,0 +1,67 @@
+// Server module — store-and-forward, management
+
+export type {
+  ForwardRequest,
+  ForwardAck,
+  ForwardDeliver,
+  ForwardPurge,
+  StoredMessage,
+  RetentionPolicy,
+} from './store-forward.js';
+export {
+  FORWARD_CHANNEL,
+  MAX_SKIP_THRESHOLD,
+  defaultRetentionPolicy,
+  MessageStore,
+  DeduplicationTracker,
+} from './store-forward.js';
+
+export type {
+  ManagementConfig,
+  PeerInfo,
+  QueueInfo,
+  PeerRelayStats,
+  RelayStats,
+  PeersResponse,
+  QueuesResponse,
+  RelayStatsResponse,
+  HealthResponse,
+} from './management.js';
+export {
+  defaultManagementConfig,
+  ManagementState,
+  ManagementServer,
+  createManagementServer,
+} from './management.js';
+
+/** Server mode configuration posture (spec 10.2). */
+export interface ServerConfig {
+  meshEnabled: boolean;
+  relayWilling: boolean;
+  relayCapacity: number;
+  storeForwardEnabled: boolean;
+  storeForwardMaxPerPeer: number;
+  storeForwardMaxAgeMs: number;
+  storeForwardMaxTotalSize: number;
+  sessionExpiryMs: number;
+  heartbeatIntervalMs: number;
+  reconnectMaxDurationMs: number | null;
+  headless: boolean;
+}
+
+/** Default server configuration. */
+export function defaultServerConfig(): ServerConfig {
+  return {
+    meshEnabled: true,
+    relayWilling: true,
+    relayCapacity: 100,
+    storeForwardEnabled: true,
+    storeForwardMaxPerPeer: 1000,
+    storeForwardMaxAgeMs: 7 * 24 * 60 * 60 * 1000,        // 7 days
+    storeForwardMaxTotalSize: 1_073_741_824,                // 1 GB
+    sessionExpiryMs: 7 * 24 * 60 * 60 * 1000,              // 7 days
+    heartbeatIntervalMs: 60_000,                            // 60s
+    reconnectMaxDurationMs: null,                           // indefinite
+    headless: true,
+  };
+}

package/src/server/management.ts

@@ -0,0 +1,285 @@
+// Management API for server-mode peers (spec 10.5, 10.7).
+//
+// Opt-in REST/JSON HTTP API bound to 127.0.0.1:9090 by default.
+// Bearer token authentication with constant-time comparison.
+
+import { createServer, IncomingMessage, ServerResponse, Server } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Management API configuration. */
+export interface ManagementConfig {
+  /** Whether the management API is enabled. Default: false. */
+  enabled: boolean;
+  /** Bind address. Default: '127.0.0.1'. */
+  bindAddress: string;
+  /** Port. Default: 9090. */
+  port: number;
+  /** Bearer token for authentication. */
+  authToken: string;
+}
+
+/** Default management API configuration. */
+export function defaultManagementConfig(): ManagementConfig {
+  return {
+    enabled: false,
+    bindAddress: '127.0.0.1',
+    port: 9090,
+    authToken: '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+/** Information about a paired peer. */
+export interface PeerInfo {
+  peerId: string;
+  name: string;
+  connected: boolean;
+  lastSeen: string | null;
+}
+
+/** Per-peer store-and-forward queue info. */
+export interface QueueInfo {
+  peerId: string;
+  pendingMessages: number;
+  oldestMessageAgeSecs: number | null;
+  totalBytes: number;
+}
+
+/** Per-peer relay statistics. */
+export interface PeerRelayStats {
+  peerId: string;
+  bytesRelayed: number;
+  activeStreams: number;
+}
+
+/** Relay statistics overview. */
+export interface RelayStats {
+  activeConnections: number;
+  perPeer: PeerRelayStats[];
+}
+
+/** Response for GET /peers. */
+export interface PeersResponse {
+  peers: PeerInfo[];
+}
+
+/** Response for GET /queues. */
+export interface QueuesResponse {
+  queues: QueueInfo[];
+}
+
+/** Response for GET /relay/stats. */
+export interface RelayStatsResponse {
+  relay: RelayStats;
+}
+
+/** Response for GET /health. */
+export interface HealthResponse {
+  status: 'healthy' | 'degraded';
+  uptimeSecs: number;
+  connectedPeers: number;
+  totalPeers: number;
+}
+
+// ---------------------------------------------------------------------------
+// Shared state
+// ---------------------------------------------------------------------------
+
+/** Shared state accessible by all management API handlers. */
+export class ManagementState {
+  readonly authTokenBytes: Buffer;
+  peers: PeerInfo[] = [];
+  queues: QueueInfo[] = [];
+  relayStats: RelayStats = { activeConnections: 0, perPeer: [] };
+  readonly startedAt: number;
+
+  constructor(authToken: string) {
+    this.authTokenBytes = Buffer.from(authToken, 'utf-8');
+    this.startedAt = Date.now();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Authentication
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a bearer token using constant-time comparison.
+ * Returns true if the token matches.
+ */
+function validateToken(provided: string, expected: Buffer): boolean {
+  const providedBytes = Buffer.from(provided, 'utf-8');
+  if (providedBytes.length !== expected.length) {
+    // Still do a comparison against expected to avoid timing leak on length.
+    timingSafeEqual(expected, expected);
+    return false;
+  }
+  return timingSafeEqual(providedBytes, expected);
+}
+
+/**
+ * Extract bearer token from Authorization header.
+ * Returns the token string or null if not present/malformed.
+ */
+function extractBearerToken(req: IncomingMessage): string | null {
+  const header = req.headers['authorization'];
+  if (!header || !header.startsWith('Bearer ')) {
+    return null;
+  }
+  return header.slice(7);
+}
+
+// ---------------------------------------------------------------------------
+// Route handling
+// ---------------------------------------------------------------------------
+
+function sendJson(res: ServerResponse, status: number, data: unknown): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+function handlePeers(state: ManagementState, res: ServerResponse): void {
+  const response: PeersResponse = { peers: state.peers };
+  sendJson(res, 200, response);
+}
+
+function handleQueues(state: ManagementState, res: ServerResponse): void {
+  const response: QueuesResponse = { queues: state.queues };
+  sendJson(res, 200, response);
+}
+
+function handleRelayStats(state: ManagementState, res: ServerResponse): void {
+  const response: RelayStatsResponse = { relay: state.relayStats };
+  sendJson(res, 200, response);
+}
+
+function handleHealth(state: ManagementState, res: ServerResponse): void {
+  const totalPeers = state.peers.length;
+  const connectedPeers = state.peers.filter((p) => p.connected).length;
+  const uptimeSecs = Math.floor((Date.now() - state.startedAt) / 1000);
+  const status = connectedPeers > 0 ? 'healthy' : 'degraded';
+
+  const response: HealthResponse = {
+    status,
+    uptimeSecs,
+    connectedPeers,
+    totalPeers,
+  };
+  sendJson(res, 200, response);
+}
+
+function handlePairingQr(res: ServerResponse): void {
+  sendJson(res, 503, {
+    error: 'pairing QR generation not yet available (pending headless pairing integration)',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and start the management API HTTP server.
+ *
+ * Returns a handle with `close()` to stop the server.
+ *
+ * @throws Error if authToken is empty.
+ */
+export function createManagementServer(
+  config: ManagementConfig,
+  state: ManagementState,
+): ManagementServer {
+  if (config.authToken === '') {
+    throw new Error('management API auth token is empty');
+  }
+
+  // Warn on non-loopback bind address.
+  if (config.bindAddress !== '127.0.0.1' && config.bindAddress !== '::1') {
+    console.warn(
+      `Management API exposed on non-loopback interface ${config.bindAddress} without TLS. This is insecure.`,
+    );
+  }
+
+  const server = createServer((req, res) => {
+    // Authentication.
+    const token = extractBearerToken(req);
+    if (token === null || !validateToken(token, state.authTokenBytes)) {
+      sendJson(res, 401, { error: 'unauthorized' });
+      return;
+    }
+
+    // Routing.
+    const url = req.url ?? '/';
+    const method = req.method ?? 'GET';
+
+    if (method !== 'GET') {
+      sendJson(res, 405, { error: 'method not allowed' });
+      return;
+    }
+
+    switch (url) {
+      case '/peers':
+        handlePeers(state, res);
+        break;
+      case '/queues':
+        handleQueues(state, res);
+        break;
+      case '/relay/stats':
+        handleRelayStats(state, res);
+        break;
+      case '/health':
+        handleHealth(state, res);
+        break;
+      case '/pairing/qr':
+        handlePairingQr(res);
+        break;
+      default:
+        sendJson(res, 404, { error: 'not found' });
+        break;
+    }
+  });
+
+  return new ManagementServer(server, config);
+}
+
+/** Handle to a running management API server. */
+export class ManagementServer {
+  private readonly _server: Server;
+  private readonly _config: ManagementConfig;
+
+  constructor(server: Server, config: ManagementConfig) {
+    this._server = server;
+    this._config = config;
+  }
+
+  /** Start listening. Returns a promise that resolves when the server is ready. */
+  async start(): Promise<void> {
+    return new Promise((resolve) => {
+      this._server.listen(this._config.port, this._config.bindAddress, () => {
+        resolve();
+      });
+    });
+  }
+
+  /** Stop the server. */
+  async close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this._server.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  /** The underlying http.Server (for testing). */
+  get httpServer(): Server {
+    return this._server;
+  }
+}