@makerclay/core

License: First Million Stays Yours License. Free to use, no matter who you are or what you use it for. It only ever costs money if you sell or host a product built on this software and that product makes you more than $1M in a year. Under that line you owe nothing, sign nothing, register nowhere.

| Free under | Above it | Becomes MIT | |---|---|---| | $1M/year from products built on it | 3% of the excess | 2028-02-20 (this version) |

Plain answers: hyperclay.com/host-program · binding text in LICENSE · questions: [email protected]

The host for malleable documents, as an embeddable Express app.

This is the engine behind makerclay. If you want to run a server, install that instead. Install this when you are building the server: a desktop app, a different CLI, a host with its own auth.

import express from 'express';
import { createHost, createSqliteStore } from '@makerclay/core';
import { ownerPassword } from '@makerclay/core/auth/password';

const host = createHost({
  data: './my-data',
  store: createSqliteStore(),
  auth: ownerPassword(),
});

await host.ready;
express().use(host.app).listen(4600);

host.app is an Express app. host.ready resolves once the boot scan and any crash recovery have finished. host.close() releases the single-writer lock.

What createHost gives you

Everything under /_/ (dashboard, editor, versions, trash, uploads, share links, collections, signups, the spec's /_/meta and /_/save lanes), plus document serving for everything else. It owns one directory:

<data>/files/          documents
<data>/tenants/        one folder per signup
<data>/versions/       history, keyed by document identity
<data>/trash/          soft deletes
<data>/records/        collection submissions
<data>/makerclay.db    a sparse overlay

The store is an overlay, not a mirror. Rows exist only for state a file cannot hold: which document is private, which is trashed, who is signed in. Lose the database and the overlay rebuilds itself from the durable records under versions/, minus the credentials, which are reissued rather than invented. With state on disk and no records left to read it by, the host refuses to serve.

The pieces you can replace

| Option | What it is | |---|---| | auth | An identity provider. none() makes every request the owner (embedded/desktop). ownerPassword() is the single-owner password provider with first-run setup. Write your own: it needs identify(req) and, optionally, routes(). | | store | The metadata overlay. createSqliteStore() uses the built-in node:sqlite. null is supported and turns off everything that needs a row. | | isolation | off, untrusted (the default: tenant documents and any file the host never saved) or all. | | features | Switches for the dashboard, editor, uploads, collections, share links, signups. | | wire | Compatibility with older clients. See src/wire-compat.js, which names the deployed client behind every shim. |

Also exported: can() and the capability matrix, the path resolver, the spec's etag and header helpers, the root-attribute reader and writer, and ulid().

Invariants it will not let you break

• Every document mutation goes through host.documents.replace. Nothing else writes a managed file.
• The document root is never served statically. Every read passes the gate.
• Serving never mutates a stored file. Serve-time injection happens on the response bytes, and both injected attributes are stripped on the way back in.
• A response on any save lane is a JSON object, on every status.

Requirements

Node 22.13 or newer, for node:sqlite, which is behind a flag before then.

First Million Stays Yours License; see the matrix at the top of this README and the LICENSE file.