@makerclay/core 1.0.0

package/src/share/save-tokens.js

@@ -0,0 +1,65 @@
+import { token as mintToken } from '../util/id.js';
+
+// Spec §9 save tokens. One mechanism, two entry points: an isolated document
+// served to a principal who may write it, and a share link with an edit grant.
+// Carrying the credential in the path is what makes the same token work for
+// fetch() and EventSource alike.
+
+const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000;
+
+export function createSaveTokens({ store, nodes, clock, ids = { token: mintToken }, ttlMs = DEFAULT_TTL_MS }) {
+  function principalOf(actor) {
+    if (actor?.kind === 'owner') return 'owner';
+    if (actor?.kind === 'tenant') return `tenant:${actor.username}`;
+    return null;
+  }
+
+  async function mintFor({ actor, node, shareHash = null, grantKind = 'edit' }) {
+    if (!store || !node?.id) return null;
+    const now = clock.now();
+    const principal = shareHash ? null : principalOf(actor);
+    if (!principal && !shareHash) return null;
+
+    // A token must have a row to cascade from, so minting one materializes the
+    // node. Publishing a version does NOT: nothing under versions/ touches the
+    // store. So the two events that create a row for a file nobody has edited
+    // are a save and a token, and under the default `untrusted` isolation the
+    // token is minted on a plain GET by anyone who may write the document. One
+    // browser visit to an rsynced file is enough to give it a row.
+    const row = nodes.materialize(node);
+
+    const existing = store.findSaveToken({ nodeId: row.id, principal, shareHash, now });
+    if (existing) return existing.token;
+
+    const value = ids.token();
+    store.insertSaveToken({
+      token: value,
+      nodeId: row.id,
+      principal,
+      shareHash,
+      grantKind,
+      expiresAt: now + ttlMs,
+    });
+    return value;
+  }
+
+  function revokeForNode(nodeId) {
+    if (!store) return 0;
+    return store.deleteSaveTokensForNode(nodeId);
+  }
+
+  // A save token is a session by another name: it is the only write lane a
+  // sandboxed document has, because an opaque origin cannot send a cookie. So
+  // anything that ends a principal's sessions has to end their tokens too.
+  function revokeForPrincipal(principal) {
+    if (!store || !principal) return 0;
+    return store.deleteSaveTokensForPrincipal(principal);
+  }
+
+  function purgeExpired() {
+    if (!store) return 0;
+    return store.purgeExpiredSaveTokens(clock.now());
+  }
+
+  return { mintFor, revokeForNode, revokeForPrincipal, purgeExpired };
+}

package/src/spec/codes.js

@@ -0,0 +1,42 @@
+// The spec §3 error-code registry, plus the small set of host-scope codes
+// makerclay adds under the same open-registry rule. Every JSON error the host
+// emits names one of these, so a client can branch on `code` instead of
+// pattern-matching `msg`.
+
+export const CODES = {
+  unauthorized: 401,
+  forbidden: 403,
+  'not-found': 404,
+  'too-large': 413,
+  'invalid-document': 422,
+  conflict: 412,
+  'read-only': 403,
+  'unsupported-type': 415,
+  'payment-required': 402,
+
+  // makerclay additions, all host-scope.
+  'bad-request': 400,
+  'unsupported-media-type': 415,
+  'rate-limited': 429,
+  reserved: 410,
+  'server-error': 500,
+  unavailable: 503,
+};
+
+export function statusForCode(code) {
+  return CODES[code] || 500;
+}
+
+export class HostError extends Error {
+  constructor(code, message, status = null) {
+    super(message);
+    this.name = 'HostError';
+    this.code = code;
+    this.status = status || statusForCode(code);
+  }
+}
+
+export const notFound = (msg = 'Not found') => new HostError('not-found', msg);
+export const forbidden = (msg = 'Forbidden') => new HostError('forbidden', msg);
+export const unauthorized = (msg = 'Unauthorized') => new HostError('unauthorized', msg);
+export const conflict = (msg = 'Conflict') => new HostError('conflict', msg);

package/src/spec/meta.js

@@ -0,0 +1,52 @@
+import { can } from '../auth/can.js';
+
+// GET /_/meta (spec §5). Two scopes in one answer:
+//
+//   `spec` and `extensions` describe the HOST. They are the same for every
+//   document it serves and nothing in them belongs to any one person, so they
+//   are never gated and answer CORS-open. Gate discovery tighter than the
+//   documents themselves and a host strands its own clients.
+//
+//   `document` describes the document named by Document-URL, and it is the only
+//   part ever withheld. Withholding is by OMISSION: for a caller who may not see
+//   the document the answer is byte-identical to the answer for a document that
+//   does not exist, so /_/meta can never be used to probe.
+
+export const SPEC_VERSION = 1;
+
+function extensionList(capabilities = {}) {
+  const names = [];
+  if (capabilities.conditional !== false) names.push('conditional');
+  if (capabilities.sync !== false) names.push('sync');
+  if (capabilities.format !== false) names.push('format');
+  if (capabilities.upload !== false) names.push('upload');
+  return names;
+}
+
+export function hostMeta(capabilities) {
+  return { spec: SPEC_VERSION, extensions: extensionList(capabilities) };
+}
+
+export function documentBlock({ node, etag, actor, ctx, limits, isolated, capabilities = {} }) {
+  const writable = can(actor, 'write', node, ctx);
+  const block = {
+    etag,
+    writable,
+    versions: true,
+    signups: !!node.signups,
+    isolated: !!isolated,
+    maxBytes: limits.saveBytes ?? null,
+  };
+  // Whether this caller may upload to THIS document, which is the question a
+  // client has to answer before it offers someone a file picker. Uploading is
+  // writing to the document by another route, so it is the write permission that
+  // decides it, never a separate one. `allowed: false` is still an answer and is
+  // reported as one: a client that sees no `upload` key at all cannot tell a host
+  // that refuses this person from a host that has no uploads.
+  if (capabilities.upload !== false) {
+    block.upload = writable
+      ? { allowed: true, maxBytes: limits.uploadBytes ?? null }
+      : { allowed: false };
+  }
+  return block;
+}

package/src/spec/wire.js

@@ -0,0 +1,115 @@
+import crypto from 'node:crypto';
+
+// Reading the Malleable HTML File wire contract off an Express request. One home
+// so the save lane, the upload lane and the sync relay cannot drift on how a
+// request names its target document or on which body shapes count.
+
+// Spec §3: a request names the document it targets with a `Document-URL` header.
+// Every shipping client still sends the pre-spec `Page-URL` (clayjs 0.2.0 sends
+// only that), so both are read and `Document-URL` wins.
+export function documentUrlHeader(req) {
+  return req?.headers?.['document-url'] || req?.headers?.['page-url'] || null;
+}
+
+// Spec §3: `/_/save` takes the document as text and has exactly one body shape,
+// so a JSON envelope is refused rather than guessed at. Compares the media type
+// only, ignoring parameters like `; charset=utf-8`, and covers the `+json`
+// structured suffix.
+export function isJsonContentType(contentType) {
+  const mediaType = String(contentType || '').split(';')[0].trim().toLowerCase();
+  return mediaType === 'application/json' || mediaType.endsWith('+json');
+}
+
+// Spec §3: the save body is the document, as text. One route, one body shape.
+// Anything else a save needs to say travels in a header, which is how §6's
+// `conditional` capability added `If-Match` without touching the body. A JSON
+// body is refused with 415 rather than guessed at: a host that quietly wrote the
+// envelope's `content` would be inventing a second shape for the one route the
+// spec says has only one.
+export function readSaveBody(req) {
+  if (isJsonContentType(req.headers['content-type'])) {
+    return { ok: false, code: 'unsupported-media-type', msg: '/_/save takes the document as text, not JSON.' };
+  }
+  return { ok: true, content: typeof req.body === 'string' ? req.body : null };
+}
+
+// Spec §6: an `etag` stamps the bytes the host STORED, never the bytes it was
+// sent. The two differ whenever a document carries formathtml="true" and is
+// reformatted before storage, so stamping the sent bytes would tell a client its
+// disk contains something it does not.
+export function documentEtag(storedHtml) {
+  return crypto.createHash('sha256').update(storedHtml ?? '').digest('hex').substring(0, 16);
+}
+
+// Does an If-Match field value permit writing over these stored bytes?
+//
+// Our own clients send one bare stamp, but RFC 9110 §13.1.1 spells the field as
+// `*` or a comma-separated list of entity-tags, each optionally quoted and weak.
+// A third-party client on a public spec that follows HTTP would otherwise get a
+// 412 it could never explain. `*` asks only that the document exist at all. Weak
+// tags count as matches, which is looser than the RFC's strong comparison and
+// deliberate: our stamp is a digest of the exact stored bytes, so there is no
+// weak form of it to confuse it with.
+//
+// An empty or absent field value matches nothing, so a client that computed its
+// stamp wrong is refused rather than quietly dropped back to last-write-wins.
+export function ifMatchSatisfied(fieldValue, storedBytes) {
+  const stored = storedBytes || '';
+  const field = String(fieldValue ?? '').trim();
+  if (field === '*') return stored.length > 0;
+
+  const current = documentEtag(stored);
+  return field.split(',').some((entry) => {
+    const tag = entry.trim().replace(/^W\//i, '').replace(/^"(.*)"$/, '$1');
+    return tag !== '' && tag === current;
+  });
+}
+
+export function ifMatchHeader(req) {
+  return req?.headers?.['if-match'] ?? null;
+}
+
+// Spec §9: advisory provenance. `user` is a human gesture, `auto` is autosave or
+// script, and an unknown value reads as `auto`. Never security: document code
+// can say anything.
+export function saveTrigger(req) {
+  const raw = String(req?.headers?.['save-trigger'] || '').trim().toLowerCase();
+  if (raw === 'user') return 'user';
+  if (raw) return 'auto';
+  // clayjs 0.2.0 does not send Save-Trigger; it sends the platform's older
+  // provenance bit instead. [wire-compat]
+  const legacy = req?.headers?.['x-hyperclay-user-driven'];
+  if (legacy === '1') return 'user';
+  return 'auto';
+}
+
+// The path portion of a document URL, with the scheme, authority, query and
+// fragment removed and NOTHING else done to it.
+//
+// Deliberately not `new URL(href).pathname`: WHATWG normalization resolves
+// `..` segments and folds backslashes into slashes BEFORE any validation could
+// see them, which turns `Document-URL: http://host/../../etc/passwd` into a
+// silently accepted write instead of a refusal. The header is untrusted input
+// chosen by the page (spec §8), so it is validated in the shape it arrived in.
+export function rawDocumentPath(href) {
+  const raw = String(href ?? '');
+  const authority = raw.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*(.*)$/);
+  const withoutOrigin = authority ? authority[1] : raw;
+  const path = withoutOrigin.split('#')[0].split('?')[0];
+  return path === '' ? '/' : path;
+}
+
+// The realm-relative document a request names. Takes an ALREADY-DECODED path:
+// decoding happens exactly once, in the caller, for the same reason the read
+// lane decodes once. A browser sends `Document-URL: .../50%25%20off.html`, and
+// decoding zero times lands the save in a new file literally named
+// `50%25%20off.html`; decoding twice turns `%252e%252e` back into `..`.
+export function resolveDocumentHref(decodedPath) {
+  let target = String(decodedPath ?? '').replace(/^\/+/, '');
+  if (target === '') return 'index.html';
+  if (target.endsWith('/')) return `${target}index.html`;
+
+  // Collapse an SPA tail: `blog/app.html/dashboard` addresses `blog/app.html`.
+  const match = target.match(/^(.*?\.(?:html|htmlclay))(?:\/.*)?$/i);
+  return match ? match[1] : target;
+}

package/src/store/index.js

@@ -0,0 +1,29 @@
+// The store-driver interface.
+//
+// The store is an OVERLAY, not a mirror: a row exists only for state a file
+// cannot hold. Every document still serves, every version still lists and
+// restores, with the store deleted. `store: null` is a supported configuration
+// (no shares, no private, no tenants, no collections, no dashboard state) and
+// the host is still a conforming spec host in it.
+//
+// A driver implements:
+//
+//   open({ paths, clock })            -> void, applies migrations
+//   close()                           -> void
+//   tx(fn)                            -> runs fn inside one transaction
+//   nextSeq()                         -> number, the global change cursor
+//
+//   getNode(owner, path)              -> row | null   (live rows only)
+//   getNodeById(id)                   -> row | null   (including tombstoned)
+//   listNodes({ owner, prefix, includeDeleted, sinceSeq }) -> row[]
+//   insertNode(row)                   -> row
+//   updateNode(id, patch)             -> row | null
+//   tombstone(id, at)                 -> row | null
+//   deleteNode(id)                    -> boolean
+//
+//   getKv(key) / setKv(key, value) / deleteKv(key)
+//
+//   plus table CRUD for shares, tenants, sessions, save_tokens, collections,
+//   record_auth and operations (see sqlite.js for the shapes).
+
+export { createSqliteStore } from './sqlite.js';

package/src/store/migrations/001-init.sql

@@ -0,0 +1,114 @@
+-- The overlay. A row exists only for a path that has state or history.
+CREATE TABLE nodes (
+  id           TEXT PRIMARY KEY,
+  owner        TEXT NOT NULL DEFAULT '',
+  path         TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  -- Two digests, two meanings. The rule that keeps them apart: THE SCANNER
+  -- NEVER WRITES A COLUMN A CLIENT-FACING DECISION READS. It used to write
+  -- `etag`, so once it had seen a terminal edit the kernel compared the file
+  -- against itself, found no drift, and let a stale tab destroy that edit.
+  --   etag           the bytes the KERNEL last wrote. Null means the host has
+  --                  never vouched for this file, which is what decides the
+  --                  default sandbox. Also the drift baseline: bytes on disk
+  --                  that do not match it were put there by something else.
+  --   observed_etag  the bytes the SCANNER last saw on disk. Read by nothing
+  --                  that answers a request.
+  etag          TEXT,
+  observed_etag TEXT,
+  bytes        INTEGER,
+  mtime_ms     REAL,
+  -- Identity, in a later step: (dev, ino) is how a file is recognised after it
+  -- moves. `ino` is TEXT holding a canonical decimal string, because a Windows
+  -- NTFS file index is 64-bit and collapses above 2^53 as a JS number.
+  dev          INTEGER,
+  ino          TEXT,
+  seq          INTEGER NOT NULL,
+  created_at   INTEGER NOT NULL,
+  updated_at   INTEGER NOT NULL,
+  deleted_at   INTEGER,
+  private      INTEGER NOT NULL DEFAULT 0,
+  isolated     INTEGER,
+  signups      INTEGER NOT NULL DEFAULT 0,
+  source_id    TEXT REFERENCES nodes(id) ON DELETE SET NULL
+);
+-- Uniqueness holds over LIVE rows only. A tombstoned row keeps its original
+-- path, because that is how restore knows where the bytes came from, so a
+-- table-level UNIQUE(owner, path) would make a trashed name permanently
+-- unusable: trash `todo.html`, and you could never create another one.
+CREATE UNIQUE INDEX nodes_live_path ON nodes(owner, path) WHERE deleted_at IS NULL;
+CREATE INDEX nodes_live ON nodes(owner, deleted_at, path);
+CREATE INDEX nodes_seq  ON nodes(seq);
+-- Deliberately not unique: hardlinks give two live paths one inode.
+CREATE INDEX nodes_inode ON nodes(dev, ino) WHERE deleted_at IS NULL;
+
+CREATE TABLE shares (
+  token_hash   TEXT PRIMARY KEY,
+  node_id      TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  grant_kind   TEXT NOT NULL,
+  label        TEXT,
+  created_at   INTEGER NOT NULL,
+  expires_at   INTEGER,
+  revoked_at   INTEGER,
+  last_used_at INTEGER
+);
+CREATE INDEX shares_node ON shares(node_id);
+
+CREATE TABLE tenants (
+  username      TEXT PRIMARY KEY,
+  password_hash TEXT NOT NULL,
+  recovery_hash TEXT,
+  source_id     TEXT REFERENCES nodes(id) ON DELETE SET NULL,
+  created_at    INTEGER NOT NULL,
+  approved_at   INTEGER,
+  disabled_at   INTEGER,
+  bytes_used    INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE sessions (
+  token_hash   TEXT PRIMARY KEY,
+  principal    TEXT NOT NULL,
+  created_at   INTEGER NOT NULL,
+  expires_at   INTEGER NOT NULL,
+  last_seen_at INTEGER
+);
+CREATE INDEX sessions_gc ON sessions(expires_at);
+
+CREATE TABLE save_tokens (
+  token      TEXT PRIMARY KEY,
+  node_id    TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  principal  TEXT,
+  share_hash TEXT REFERENCES shares(token_hash) ON DELETE CASCADE,
+  grant_kind TEXT NOT NULL,
+  expires_at INTEGER NOT NULL
+);
+CREATE INDEX save_tokens_gc ON save_tokens(expires_at);
+CREATE INDEX save_tokens_node ON save_tokens(node_id);
+
+CREATE TABLE collections (
+  node_id      TEXT PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  slug         TEXT UNIQUE NOT NULL,
+  submit_token TEXT NOT NULL,
+  accepting    INTEGER NOT NULL DEFAULT 1,
+  role_map     TEXT,
+  created_at   INTEGER NOT NULL
+);
+
+CREATE TABLE record_auth (
+  node_id      TEXT PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  code_hash    TEXT NOT NULL,
+  failures     INTEGER NOT NULL DEFAULT 0,
+  locked_until INTEGER,
+  deleted_at   INTEGER
+);
+
+CREATE TABLE operations (
+  id           TEXT PRIMARY KEY,
+  kind         TEXT NOT NULL,
+  node_id      TEXT,
+  phase        TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  started_at   INTEGER NOT NULL
+);
+
+CREATE TABLE kv (k TEXT PRIMARY KEY, v TEXT);