PlainSDK (JavaScript)

TypeScript server runtime for PlainWeb in any fetch() environment (e.g. Cloudflare Workers, Deno Deploy).

Features

• Verify incoming PlainWeb requests
• Sign responses
• Built-in /outbox handling

Example

import { PlainServer, ServerRequest, ServerResponse } from "./src/main";

const handler = async (req: ServerRequest, res: ServerResponse) => {
  if (!req.sub) return await res.unauthorized("Unauthorized");
  if (req.path === "/status") return await res.success("# OK");
  return await res.success("Hello, PlainWeb!");
};

let server: PlainServer | null = null;
export default {
  async fetch(request: Request, env?: { ED25519_SEED_HEX?: string }) {
    server ??= new PlainServer(handler, { seedHex: env?.ED25519_SEED_HEX });
    return await server.handleRequest(request);
  },
};

Demo worker (public + auth-required + KV)

This repo includes a demo Cloudflare Worker at src/demo-worker.ts with:

• Public (no auth): / and /guess
• Private (requires Plain auth / sub): /private

“Login” in this demo means the request is authenticated by Plain (client sends x-plain-sub + signature headers, so req.sub is present).

Guess the number (minigame)

• Public route: /guess
• Make a guess by sending input as a raw query string:
  • /guess?12
• Reset:
  • /guess?reset

If the request is authenticated (req.sub present), the game state is stored in Cloudflare KV keyed by sub (binding: GAME_KV).

Run

npm install
npm run dev

Generate a seed:

npm run gen:ed25519-seed

Set ED25519_SEED_HEX (64 hex chars) in .dev.vars (local) / Wrangler secret (prod).