@lobsterhoney/edge

Edge middleware for serving signed dynamic content from your control plane.

Fetches signed, server-authored content from your control-plane origin and serves it at the edge. All content is constructed server-side; this package ships no content generators. Works on Vercel, Cloudflare Workers, Netlify Edge, and Node.

Install

npm install @lobsterhoney/edge

Configuration

interface EdgeConfig {
  apiKey: string;          // Required. API key for your control plane.
  orgSlug: string;         // Required. Organization slug.
  manifestUrl: string;     // Required. Your control-plane ORIGIN, e.g.
                           //   https://<your-lobsterhoney-origin>. Origin only;
                           //   the client derives the rest of the path itself.
  trustBundle: TrustBundle;// Required. The signed trust bundle issued to you at
                           //   onboarding. Pinned here as the sole root of trust
                           //   (the client fails closed without it).
  siteId?: string;         // Optional. Scope to a specific site.
  hitReportUrl?: string;   // Optional. Override where events are POSTed. Defaults
                           //   to the manifestUrl origin.
}

apiKey, orgSlug, manifestUrl, and trustBundle are required. There is no hardcoded control-plane host and no remote trust fetch: you supply the origin, and you pin the trustBundle you were issued at onboarding. manifestUrl is an origin (for example https://<your-lobsterhoney-origin>), not a full path; the client derives its endpoints from that origin. Leave hitReportUrl unset in the normal setup so events post to the same origin; set it only if you route reporting through a separate collector.

The trustBundle and your control-plane origin are provided during onboarding. Store the origin in an env var (LOBSTERHONEY_URL below) so you can switch hosts without editing code.

Environment variables

The examples read two env vars (set them in your platform's project settings / secrets):

| Variable | Maps to | Example | |----------|---------|---------| | LOBSTERHONEY_KEY | apiKey | your control-plane API key | | LOBSTERHONEY_URL | manifestUrl | https://<your-lobsterhoney-origin> |

The examples below assume a pinned bundle in scope:

import type { TrustBundle } from '@lobsterhoney/edge';

// The signed bundle issued to you at onboarding (store it as JSON in your repo
// or a secret, and load it here). Shown abbreviated:
const trustBundle: TrustBundle = {
  version: 1,
  issuedAt: '2026-01-01T00:00:00.000Z',
  keys: [
    {
      kid: 'your-key-id',
      alg: 'ES256',
      publicKey: { /* JWK issued to you */ },
      status: 'active',
      validFrom: '2026-01-01T00:00:00.000Z',
      validUntil: '2027-01-01T00:00:00.000Z',
    },
  ],
};

Vercel

// middleware.ts
import { createMiddleware } from '@lobsterhoney/edge/vercel';

const middleware = createMiddleware({
  apiKey: process.env.LOBSTERHONEY_KEY!,
  orgSlug: 'your-org',
  manifestUrl: process.env.LOBSTERHONEY_URL!, // origin only
  trustBundle,
});

export default middleware;

Cloudflare Workers

The handler returns a Response for a matched path and null otherwise, so fall through to your origin (or fetch(request)) when it returns null. Pass the Worker ctx through so hit reporting runs in the background via waitUntil.

import { createCloudflareHandler } from '@lobsterhoney/edge/cloudflare';

const handler = createCloudflareHandler({
  apiKey: 'YOUR_API_KEY',      // e.g. from env.LOBSTERHONEY_KEY
  orgSlug: 'your-org',
  manifestUrl: 'https://<your-lobsterhoney-origin>', // origin only
  trustBundle,
});

export default {
  async fetch(request, env, ctx) {
    const res = await handler(request, env, ctx);
    return res ?? fetch(request); // null => no match, serve the real origin
  },
};

Netlify Edge

import { createNetlifyHandler } from '@lobsterhoney/edge/netlify';

export default createNetlifyHandler({
  apiKey: Deno.env.get('LOBSTERHONEY_KEY')!,
  orgSlug: 'your-org',
  manifestUrl: Deno.env.get('LOBSTERHONEY_URL')!, // origin only
  trustBundle,
});

Express / Node

import express from 'express';
import { createExpressMiddleware } from '@lobsterhoney/edge/node';

const app = express();
app.use(createExpressMiddleware({
  apiKey: process.env.LOBSTERHONEY_KEY!,
  orgSlug: 'your-org',
  manifestUrl: process.env.LOBSTERHONEY_URL!, // origin only
  trustBundle,
}));

Reporting

Each middleware adapter reports request metadata to your control plane. The event carries metadata only (method, host, client IP, and the ordered list of request header names, never header values or the request body). Delivery is fire-and-forget: it uses keepalive, never throws, and no-ops when no report URL can be resolved. With hitReportUrl unset (the default), events post to the manifestUrl origin.

TypeScript

The public types are exported from the root entrypoint:

import type { EdgeConfig, TrustBundle } from '@lobsterhoney/edge';

Security notes

• Zero runtime dependencies. Uses only the Web Crypto API, so it runs on Cloudflare Workers, Vercel Edge, Netlify Edge (Deno), and Node 18+ without a bundler shim.
• No hardcoded backend host. You supply manifestUrl; the client derives its endpoints from that origin.
• Pinned trust, fail closed. You pin the trustBundle you were issued; there is no remote trust fetch. Manifests are ECDSA (P-256) verified against that pinned bundle before any content is served: the signing key is selected by key id, checked against the bundle's revoked-key list and validity window, and the manifest's own expiresAt is enforced. Construction throws if no bundle is pinned.
• Minimal telemetry. Reported events include header names, not values, and never the request body.
• Session cookie is __Host--prefixed (host-locked, Secure, path /) and validated as a UUID on read.

License

MIT