blossom-mock-server

In-memory Blossom mock server for deterministic JavaScript and TypeScript tests.

Use it when your app or package needs to test Blossom blob upload and retrieval behavior without depending on an online server, network state, remote data, moderation policy, rate limits, authentication, or persistence.

Features

• HTTP Blossom server interface for tests.
• In-memory storage per server instance.
• BUD-01 blob retrieval: GET /<sha256> and HEAD /<sha256>.
• Optional file extensions on retrieval URLs.
• BUD-02 blob upload: PUT /upload.
• SHA-256 addressing over the exact uploaded bytes.
• Blob descriptor responses with url, sha256, size, type, and uploaded.
• Basic byte range support for GET.
• CORS headers on all responses.
• No auth, no persistence, no CLI.

Requirements

Node.js >=24.

Install

npm install blossom-mock-server

Usage

import { createMockBlossomServer } from "blossom-mock-server";

const server = createMockBlossomServer();

await server.start();

try {
  console.log(server.url); // http://127.0.0.1:<port>

  const response = await fetch(`${server.url}/upload`, {
    method: "PUT",
    headers: { "Content-Type": "text/plain" },
    body: "hello blossom"
  });

  console.log(await response.json());
} finally {
  await server.stop();
}

Test Example

import { createHash } from "node:crypto";
import { createMockBlossomServer } from "blossom-mock-server";

const server = createMockBlossomServer();
await server.start();

const data = new TextEncoder().encode("hello mock server");
const sha256 = createHash("sha256").update(data).digest("hex");

const upload = await fetch(`${server.url}/upload`, {
  method: "PUT",
  headers: {
    "Content-Type": "text/plain",
    "X-SHA-256": sha256
  },
  body: data
});

console.log(upload.status); // 201

const descriptor = await upload.json();
const download = await fetch(descriptor.url);

console.log(await download.text()); // hello mock server

API

createMockBlossomServer(options?)

Creates an isolated in-memory Blossom server instance.

const server = createMockBlossomServer({
  host: "127.0.0.1",
  port: 0
});

Options:

• host?: string defaults to "127.0.0.1"
• port?: number defaults to 0

Server methods:

• await server.start() starts the HTTP server.
• await server.stop() closes the HTTP server.
• server.url is the server URL after start().
• server.seed(blobs) inserts blobs into memory.
• server.getBlobs() returns stored blobs.
• server.getBlob(sha256) returns a stored blob by hash.
• server.hasBlob(sha256) checks whether a blob exists.
• server.reset() clears stored blobs.

Protocol Scope

This package implements a focused Blossom subset for tests.

Supported endpoints:

• PUT /upload
• GET /<sha256>
• GET /<sha256>.<ext>
• HEAD /<sha256>
• HEAD /<sha256>.<ext>
• OPTIONS *

Out of scope for v1:

• BUD-11 Nostr authorization
• BUD-12 DELETE /<sha256> and GET /list/<pubkey>
• Mirror, media optimization, payment, rate limits, and persistence

License

MIT