Hono & Bun E-Signature Microservice: Sub-5ms Edge Signing (2026)

# Initialize Bun application
bun init -y

# Install lightweight web framework and schema validation
bun add hono zod

# Create source directory
mkdir -p src

import { Hono } from "hono";
import { z } from "zod";
import type { ServerWebSocket } from "bun";

// ==========================================
// 1. CONFIGURATION & ENVIRONMENT VALIDATION
// ==========================================
const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY;
const SIGNBEE_WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET;
const INTERNAL_SERVICE_TOKEN = process.env.INTERNAL_SERVICE_TOKEN;
const PORT = parseInt(process.env.PORT || "3000", 10);

if (!SIGNBEE_API_KEY || !SIGNBEE_WEBHOOK_SECRET || !INTERNAL_SERVICE_TOKEN) {
  throw new Error("Missing required environment variables. Check .env configuration.");
}

// ==========================================
// 2. IN-MEMORY LRU EVENT CACHE
// ==========================================
interface ContractEvent {
  documentId: string;
  event: string;
  timestamp: number;
  recipientEmail?: string;
  metadata?: Record<string, unknown>;
}

class EventRingBuffer {
  private capacity: number;
  private buffer: Map<string, ContractEvent[]>;

  constructor(capacity = 500) {
    this.capacity = capacity;
    this.buffer = new Map();
  }

  push(documentId: string, event: ContractEvent) {
    const existing = this.buffer.get(documentId) || [];
    existing.push(event);
    if (existing.length > 50) {
      existing.shift();
    }
    this.buffer.set(documentId, existing);

    // Evict oldest documents if capacity exceeded
    if (this.buffer.size > this.capacity) {
      const oldestKey = this.buffer.keys().next().value;
      if (oldestKey) this.buffer.delete(oldestKey);
    }
  }

  get(documentId: string): ContractEvent[] {
    return this.buffer.get(documentId) || [];
  }
}

const eventCache = new EventRingBuffer(1000);

// ==========================================
// 3. ZOD CONTRACT SCHEMAS
// ==========================================
const SignerSchema = z.object({
  name: z.string().min(1, "Signer name is required"),
  email: z.string().email("Invalid signer email address"),
  role: z.string().default("signer"),
});

const SendContractSchema = z.object({
  title: z.string().min(3, "Title must be at least 3 characters"),
  markdown: z.string().min(10, "Markdown content is required"),
  signers: z.array(SignerSchema).min(1, "At least one signer is required"),
  expiresInDays: z.number().int().positive().default(14),
  metadata: z.record(z.unknown()).optional(),
});

type SendContractInput = z.infer<typeof SendContractSchema>;

// ==========================================
// 4. TIMING-SAFE HMAC VERIFICATION (WEB CRYPTO)
// ==========================================
async function verifyHmacSignature(
  rawBody: string,
  signatureHeader: string | undefined,
  secret: string
): Promise<boolean> {
  if (!signatureHeader) return false;

  const encoder = new TextEncoder();
  const keyData = encoder.encode(secret);

  const cryptoKey = await crypto.subtle.importKey(
    "raw",
    keyData,
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );

  const signatureBuffer = await crypto.subtle.sign(
    "HMAC",
    cryptoKey,
    encoder.encode(rawBody)
  );

  // Convert generated signature to lowercase hex string
  const hashArray = Array.from(new Uint8Array(signatureBuffer));
  const expectedSignature = hashArray
    .map((byte) => byte.toString(16).padStart(2, "0"))
    .join("");

  // Constant-time string comparison to prevent side-channel timing attacks
  const a = encoder.encode(expectedSignature);
  const b = encoder.encode(signatureHeader.trim().toLowerCase());

  if (a.byteLength !== b.byteLength) return false;

  let mismatch = 0;
  for (let i = 0; i < a.byteLength; i++) {
    mismatch |= a[i] ^ b[i];
  }

  return mismatch === 0;
}

// ==========================================
// 5. HONO APPLICATION & ROUTING
// ==========================================
const app = new Hono();

// Auth Middleware for Internal Services
const internalAuthMiddleware = async (c: any, next: () => Promise<void>) => {
  const authHeader = c.req.header("Authorization");
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return c.json({ error: "Unauthorized: Missing or malformed Bearer token" }, 401);
  }

  const token = authHeader.replace("Bearer ", "").trim();
  if (token !== INTERNAL_SERVICE_TOKEN) {
    return c.json({ error: "Forbidden: Invalid service credentials" }, 403);
  }

  await next();
};

// Health Check
app.get("/health", (c) => {
  return c.json({ status: "healthy", runtime: "bun", framework: "hono", timestamp: Date.now() });
});

// Endpoint: Dispatch New Contract via Signbee API
app.post("/api/contracts/send", internalAuthMiddleware, async (c) => {
  const startTime = performance.now();

  const body = await c.req.json().catch(() => null);
  const parseResult = SendContractSchema.safeParse(body);

  if (!parseResult.success) {
    return c.json(
      { error: "Validation failed", details: parseResult.error.flatten() },
      422
    );
  }

  const data: SendContractInput = parseResult.data;

  // Direct native HTTP dispatch to Signbee API
  try {
    const response = await fetch("https://api.signb.ee/v1/documents/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": SIGNBEE_API_KEY,
      },
      body: JSON.stringify({
        title: data.title,
        markdown: data.markdown,
        signers: data.signers,
        expires_in_days: data.expiresInDays,
        metadata: data.metadata,
      }),
    });

    const result = await response.json();

    if (!response.ok) {
      return c.json(
        { error: "Signbee dispatch rejected", upstreamStatus: response.status, details: result },
        response.status
      );
    }

    const durationMs = (performance.now() - startTime).toFixed(2);

    return c.json({
      success: true,
      documentId: result.document_id,
      signingUrl: result.signing_url,
      status: result.status,
      latencyMs: parseFloat(durationMs),
    }, 201);
  } catch (err: any) {
    return c.json(
      { error: "Failed to dispatch contract upstream", message: err.message },
      502
    );
  }
});

// Endpoint: Webhook Ingestion & Verification
app.post("/api/webhooks/signbee", async (c) => {
  const signature = c.req.header("x-signbee-signature");
  const rawBody = await c.req.raw.text();

  const isValid = await verifyHmacSignature(
    rawBody,
    signature,
    SIGNBEE_WEBHOOK_SECRET
  );

  if (!isValid) {
    return c.json({ error: "Invalid cryptographic HMAC signature" }, 401);
  }

  let payload: any;
  try {
    payload = JSON.parse(rawBody);
  } catch {
    return c.json({ error: "Malformed JSON payload" }, 400);
  }

  const documentId = payload.document_id;
  const eventName = payload.event; // e.g., "document.signed", "document.completed"

  const eventData: ContractEvent = {
    documentId,
    event: eventName,
    timestamp: payload.timestamp || Date.now(),
    recipientEmail: payload.recipient?.email,
    metadata: payload.metadata,
  };

  // 1. Buffer in memory
  eventCache.push(documentId, eventData);

  // 2. Broadcast via Bun WebSocket to connected UI clients
  // @ts-ignore - access Bun server instance bound at runtime
  if (server) {
    server.publish(
      `contract:${documentId}`,
      JSON.stringify({ type: "CONTRACT_UPDATE", data: eventData })
    );
    server.publish(
      "all-contracts",
      JSON.stringify({ type: "GLOBAL_UPDATE", data: eventData })
    );
  }

  return c.json({ received: true, event: eventName, documentId });
});

// Endpoint: Retrieve In-Memory Audit Trail for a Document
app.get("/api/contracts/:id/events", internalAuthMiddleware, (c) => {
  const documentId = c.req.param("id");
  const events = eventCache.get(documentId);
  return c.json({ documentId, count: events.length, events });
});

// ==========================================
// 6. BUN SERVER & WEBSOCKET ENGINE
// ==========================================
interface WebSocketData {
  subscribedContractId?: string;
}

const server = Bun.serve<WebSocketData>({
  port: PORT,
  fetch(req, server) {
    const url = new URL(req.url);

    // Handle WebSocket Upgrades
    if (url.pathname === "/ws") {
      const contractId = url.searchParams.get("contractId");
      const success = server.upgrade(req, {
        data: { subscribedContractId: contractId || undefined },
      });
      return success ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
    }

    // Delegate standard HTTP requests to Hono
    return app.fetch(req);
  },
  websocket: {
    open(ws: ServerWebSocket<WebSocketData>) {
      if (ws.data.subscribedContractId) {
        ws.subscribe(`contract:${ws.data.subscribedContractId}`);
      } else {
        ws.subscribe("all-contracts");
      }
      ws.send(JSON.stringify({ type: "CONNECTED", timestamp: Date.now() }));
    },
    message(ws: ServerWebSocket<WebSocketData>, message: string | Buffer) {
      // Client can send dynamic subscription commands
      try {
        const parsed = JSON.parse(message.toString());
        if (parsed.action === "subscribe" && parsed.contractId) {
          ws.subscribe(`contract:${parsed.contractId}`);
          ws.send(JSON.stringify({ type: "SUBSCRIBED", topic: parsed.contractId }));
        }
      } catch {
        ws.send(JSON.stringify({ error: "Invalid WS command format" }));
      }
    },
    close(ws: ServerWebSocket<WebSocketData>) {
      if (ws.data.subscribedContractId) {
        ws.unsubscribe(`contract:${ws.data.subscribedContractId}`);
      }
      ws.unsubscribe("all-contracts");
    },
  },
});

console.log(`🚀 Signbee E-Signature Microservice active on http://localhost:${PORT}`);

// ❌ Obsolete Node.js crypto module pattern
import crypto from "node:crypto";

const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
const isValid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

"use client";

import { useEffect, useState } from "react";

export function useContractStatus(contractId: string) {
  const [status, setStatus] = useState<string>("pending");
  const [events, setEvents] = useState<any[]>([]);

  useEffect(() => {
    if (!contractId) return;

    // Connect to our Bun microservice WebSocket gateway
    const wsUrl = `ws://localhost:3000/ws?contractId=${contractId}`;
    const socket = new WebSocket(wsUrl);

    socket.onmessage = (event) => {
      try {
        const payload = JSON.parse(event.data);
        if (payload.type === "CONTRACT_UPDATE") {
          setStatus(payload.data.event);
          setEvents((prev) => [...prev, payload.data]);
        }
      } catch (err) {
        console.error("Failed to parse WebSocket message", err);
      }
    };

    socket.onerror = (error) => {
      console.error("WebSocket connection error:", error);
    };

    return () => {
      socket.close();
    };
  }, [contractId]);

  return { status, events, isCompleted: status === "document.completed" };
}

# Multi-stage production build for Bun e-signature gateway
FROM oven/bun:1.2-alpine AS base
WORKDIR /usr/src/app

# Install dependencies into temporary cache
FROM base AS install
RUN mkdir -p /temp/prod
COPY package.json bun.lock /temp/prod/
RUN cd /temp/prod && bun install --frozen-lockfile --production

# Production runtime stage
FROM base AS release
COPY --from=install /temp/prod/node_modules node_modules
COPY src src
COPY package.json .

# Run as unprivileged non-root user
USER bun
EXPOSE 3000/tcp
ENV NODE_ENV=production

CMD ["bun", "run", "src/index.ts"]