@makerclay/core 1.0.0

package/src/nodes/ops.js

@@ -0,0 +1,613 @@
+import path from 'upath';
+import crypto from 'node:crypto';
+import { can } from '../auth/can.js';
+import { HostError } from '../spec/codes.js';
+import { isDocumentPath } from '../paths.js';
+import { nameError, uniqueName, splitName, assetsDirFor } from './names.js';
+import fs from 'node:fs/promises';
+import {
+  statIfExists, rename, mkdirp, rmrf, readdirIfExists,
+  atomicWrite, fsyncDir, copyFile, createExclusive,
+} from '../util/fsx.js';
+
+// Tree operations, every one of them write-ahead journaled (§9.2).
+//
+// The filesystem and SQLite cannot share a transaction, and a best-effort
+// rollback list does not survive `kill -9`. So each op is three phases with a
+// durable record between them:
+//
+//   1. insert an `operations` row describing the intent  (phase 'planned')
+//   2. do the FS work, which is a single atomic rename   (phase 'fs-done')
+//   3. one store transaction: rewrite rows, bump seq, DELETE the operation row
+//
+// Startup then reads whatever rows survived and finishes or unwinds them
+// (recovery.js). The rename in phase 2 is the pivot: before it nothing has
+// happened, after it the metadata is merely behind.
+//
+// Invariant 2 still holds here. No function in this file writes a DOCUMENT;
+// documents move as opaque bytes (rename/copy) or go through the mutation
+// kernel. `putFile` is the one sanctioned direct write and it refuses .html.
+
+const TRASH_SEPARATOR = '__';
+
+function isInside(parent, child) {
+  return child === parent || child.startsWith(`${parent}/`);
+}
+
+export function createOps({
+  paths, nodes, store, versions, locks, events, clock, ids,
+  logger = console, replace = null, 
+}) {
+  function assert(condition, code, message) {
+    if (!condition) throw new HostError(code, message);
+  }
+
+  function authorize(actor, action, node, ctx) {
+    assert(can(actor, action, node, ctx), 'forbidden', 'You do not have permission to do that.');
+  }
+
+  function checkName(name) {
+    const problem = nameError(name);
+    assert(!problem, 'bad-request', problem || '');
+  }
+
+  // The op wrapper. `fsWork` must be idempotent-or-atomic; `commit` runs inside
+  // the store transaction and therefore must be synchronous.
+  async function runOperation({ kind, nodeId = null, payload }, fsWork, commit) {
+    const opId = ids.ulid();
+    let landed = false;
+    if (store) {
+      store.insertOperation({ id: opId, kind, nodeId, phase: 'planned', payload, startedAt: clock.now() });
+    }
+    try {
+      const fsResult = await fsWork();
+      landed = true;
+      if (store) store.setOperationPhase(opId, 'fs-done');
+      if (!store) return commit(fsResult);
+      return store.tx(() => {
+        const value = commit(fsResult);
+        store.deleteOperation(opId);
+        return value;
+      });
+    } catch (error) {
+      // The FS half is a single rename, so a throw before it landed means
+      // nothing happened and the plan is only noise. A throw after it landed
+      // leaves the row behind on purpose, for startup recovery to finish.
+      if (!landed && store) store.deleteOperation(opId);
+      throw error;
+    }
+  }
+
+  function listDescendants(owner, prefix) {
+    if (!store) return [];
+    return store.listNodes({ owner, prefix: `${prefix}/`, includeDeleted: true });
+  }
+
+  function rewriteDescendants(owner, fromPath, toPath) {
+    return listDescendants(owner, fromPath).map((row) => store.updateNode(row.id, {
+      path: `${toPath}${row.path.slice(fromPath.length)}`,
+      updatedAt: clock.now(),
+      seq: store.nextSeq(),
+    }));
+  }
+
+  // Display-only bookkeeping: the versions directory is found by the identity
+  // half of its name, so a failure here costs a nice folder name and nothing
+  // else. It must never fail a move that has already landed on disk.
+  async function moveVersionSlug(node, toPath) {
+    if (node.kind !== 'doc') return;
+    try {
+      await versions.renameSlug(node, toPath);
+    } catch (error) {
+      logger.warn?.('[makerclay] could not rename versions folder (cosmetic):', error?.message || error);
+    }
+  }
+
+  // Written after the bytes have already moved, so a failure here costs a stale
+  // record and never the operation. The boot reconcile and the next publish both
+  // repair it.
+  async function patchMetaQuietly(node, patch) {
+    try {
+      await versions.patchMeta(node, patch);
+    } catch (error) {
+      logger.warn?.('[makerclay] could not update the durable record:', error?.message || error);
+    }
+  }
+
+  // A document's uploads live in `assets-<stem>/` beside it, and the URLs the
+  // upload lane hands back are relative to the document, so the pair has to
+  // travel together or every image 404s at the new path. Done after the
+  // document's own operation rather than inside it: the journal reads which
+  // side of ONE rename a crash landed on, and a second rename inside the same
+  // step would make that unreadable. A crash between the two leaves the folder
+  // behind, which is exactly what happened every time before this existed.
+  async function carryAssets(actor, owner, from, to, ctx, run) {
+    if (!isDocumentPath(from)) return;
+    const fromAssets = assetsDirFor(from);
+    const toAssets = assetsDirFor(to);
+    if (fromAssets === toAssets) return;
+    if (!(await statIfExists(await paths.resolveWrite(owner, fromAssets)))) return;
+    // Occupied means the destination document already has assets of its own.
+    // Merging two asset folders is a guess about which file wins, so the folder
+    // stays where it is and the operation still succeeds.
+    if (await statIfExists(await paths.resolveWrite(owner, toAssets))) {
+      logger.warn?.(
+        `[makerclay] ${fromAssets} stayed put: ${toAssets} already exists.`,
+      );
+      return;
+    }
+    await run({ actor, owner, from: fromAssets, to: toAssets, ctx });
+  }
+
+  async function resolveExisting(owner, relPath) {
+    const real = await paths.resolveWrite(owner, relPath);
+    const stat = await statIfExists(real);
+    assert(stat, 'not-found', 'Not found');
+    return { real, stat };
+  }
+
+  function rowFor(owner, relPath, kind) {
+    return nodes.materialize({ ...nodes.resolve(owner, relPath, { kind }), kind });
+  }
+
+  // ---- create ------------------------------------------------------------
+
+  async function mkdir({ actor, owner = '', dir = '', name, ctx = {} }) {
+    checkName(name);
+    const relPath = dir ? `${dir}/${name}` : name;
+    const node = nodes.resolve(owner, relPath, { kind: 'dir' });
+    authorize(actor, 'write', node, ctx);
+
+    const real = await paths.resolveWrite(owner, relPath);
+    assert(!(await statIfExists(real)), 'conflict', 'Something with that name is already there.');
+
+    const created = await runOperation(
+      { kind: 'mkdir', payload: { owner, path: relPath } },
+      async () => { await mkdirp(real); await fsyncDir(path.dirname(real)); },
+      () => rowFor(owner, relPath, 'dir'),
+    );
+    events.emit('node-created', { node: created });
+    return created;
+  }
+
+  // A new document is a mutation of a document, so it goes through the kernel
+  // (invariant 2) rather than getting its own write path here. What ops adds is
+  // the parent directory and a free name.
+  async function createDocument({ actor, owner = '', dir = '', name, html, ctx = {} }) {
+    assert(replace, 'server-error', 'This host has no mutation kernel.');
+    checkName(name);
+    assert(isDocumentPath(name), 'bad-request', 'A document name must end in .html.');
+
+    const parentReal = dir ? await paths.resolveWrite(owner, dir) : paths.realmRoot(owner);
+    await mkdirp(parentReal);
+    const free = await uniqueName(parentReal, name);
+    const relPath = dir ? `${dir}/${free}` : free;
+
+    const result = await replace({
+      actor, owner, relPath, bytes: html, trigger: 'user', source: 'create', ctx,
+    });
+    events.emit('node-created', { node: result.node });
+    return { node: result.node, path: relPath, etag: result.etag, derived: result.derived };
+  }
+
+  // The one sanctioned write that does not go through the mutation kernel, and
+  // it refuses documents so that stays true. Uploads are files: same tree, same
+  // rename, same delete, same trash as everything else.
+  async function putFile({ actor, owner = '', dir = '', name, content, encoding = null, ctx = {} }) {
+    checkName(name);
+    assert(!isDocumentPath(name), 'bad-request', 'HTML files are documents: save them through the save lane.');
+
+    const parentReal = dir ? await paths.resolveWrite(owner, dir) : paths.realmRoot(owner);
+    await mkdirp(parentReal);
+    const free = await uniqueName(parentReal, name);
+    const relPath = dir ? `${dir}/${free}` : free;
+
+    const node = nodes.resolve(owner, relPath, { kind: 'file' });
+    authorize(actor, 'write', node, ctx);
+    const real = await paths.resolveWrite(owner, relPath);
+
+    const created = await runOperation(
+      { kind: 'create', payload: { owner, path: relPath } },
+      async () => {
+        await atomicWrite(real, content, encoding);
+        return await statIfExists(real);
+      },
+      (stat) => {
+        const row = rowFor(owner, relPath, 'file');
+        if (!store) return row;
+        return store.updateNode(row.id, {
+          bytes: stat ? stat.size : null,
+          mtimeMs: stat ? stat.mtimeMs : null,
+        });
+      },
+    );
+    events.emit('node-created', { node: created });
+    return { node: created, path: relPath };
+  }
+
+  // The upload lane's write, and the only place the HOST names the file rather
+  // than the person. Two things follow from that, and both are the point.
+  //
+  // The tail is the content hash, so uploading the same bytes twice converges on
+  // the file already stored instead of leaving a second copy of it. And the name
+  // is claimed with an exclusive create, never by looking for a free one first:
+  // check-then-write loses the race between two uploads of one filename, and the
+  // loser's bytes land on top of the winner's with both callers told they
+  // succeeded. `uniqueName` above has exactly that shape, which is why this does
+  // not use it.
+  //
+  // Authorization is the CALLER's job here, and it is deliberately not repeated.
+  // The permission being exercised is "may this actor write to this document",
+  // held against the document, and a save token grants precisely that and nothing
+  // else. Re-checking against the stored file's own node would fail for every
+  // token-bearing document, which is most of them.
+  async function putUpload({ owner = '', dir, name, content }) {
+    const base = path.basename(String(name || ''));
+    const { stem, ext } = splitName(base);
+    const cleanExt = nameError(`x${ext}`) ? '' : ext;
+    const cleanStem = nameError(`${stem}${cleanExt}`) || !stem ? 'file' : stem;
+
+    const parentReal = await paths.resolveWrite(owner, dir);
+    await mkdirp(parentReal);
+    const digest = crypto.createHash('sha256').update(content).digest('hex');
+
+    let chosen = null;
+    let wrote = false;
+    for (let length = 6; length <= 32 && !chosen; length += 2) {
+      const candidate = `${cleanStem}-${digest.slice(0, length)}${cleanExt}`;
+      const real = path.join(parentReal, candidate);
+      try {
+        await createExclusive(real, content);
+        chosen = candidate;
+        wrote = true;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        // Same name, so same content hash prefix: either the identical file (the
+        // common case, and the answer is the file already there) or a prefix
+        // collision between different bytes, which lengthens the tail.
+        const existing = await fs.readFile(real).catch(() => null);
+        if (existing && existing.equals(content)) chosen = candidate;
+      }
+    }
+    assert(chosen, 'server-error', 'Could not find a free name for that file.');
+
+    const relPath = `${dir}/${chosen}`;
+    const real = path.join(parentReal, chosen);
+
+    // The claim above is already atomic and self-healing, so it needs no journal
+    // to unwind: a crash between it and the row below leaves a real file that the
+    // scanner registers on the next walk, never a half-written one.
+    const node = nodes.resolve(owner, relPath, { kind: 'file' });
+    const stat = await statIfExists(real);
+    const row = store
+      ? store.tx(() => store.updateNode(nodes.materialize(node).id, {
+        bytes: stat ? stat.size : null,
+        mtimeMs: stat ? stat.mtimeMs : null,
+      }))
+      : node;
+    if (wrote) events.emit('node-created', { node: row });
+    return { node: row, path: relPath, name: chosen, bytes: content.length, created: wrote };
+  }
+
+  // ---- move --------------------------------------------------------------
+
+  async function move({ actor, owner = '', from, to, ctx = {} }) {
+    checkName(path.basename(to));
+    assert(!isInside(from, to), 'bad-request', 'A folder cannot be moved inside itself.');
+
+    const source = await resolveExisting(owner, from);
+    const node = nodes.materialize(nodes.resolve(owner, from, {
+      kind: source.stat.isDirectory() ? 'dir' : undefined,
+    }));
+    authorize(actor, 'write', node, ctx);
+
+    const targetReal = await paths.resolveWrite(owner, to);
+    assert(!(await statIfExists(targetReal)), 'conflict', 'Something with that name is already there.');
+
+    // A rename can change what the file IS. page.txt -> page.html must stop
+    // being served raw, and kind is what decides both the serve lane and the
+    // sandbox, so it is recomputed rather than carried over.
+    //
+    // Hoisted out of the commit callback because the durable record needs the
+    // same value and is written FIRST, in the FS half. Two copies of this
+    // expression drift, and the copy that drifts is the record, which is what a
+    // rebuild trusts. A directory keeps its kind whatever it is renamed to: a
+    // folder called `x.html` is still a folder.
+    const kind = nodes.kindFor(to, source.stat.isDirectory());
+
+    // Both ends take the lock, in a fixed order, so a save racing a rename
+    // cannot land bytes at a path this op is about to empty.
+    const [first, second] = [source.real, targetReal].sort();
+    let movedChildren = [];
+    const moved = await locks.withLock(first, () => locks.withLock(second, () => runOperation(
+      { kind: 'move', nodeId: node.id, payload: { owner, from, to, fromReal: source.real, toReal: targetReal } },
+      async () => {
+        await mkdirp(path.dirname(targetReal));
+        await rename(source.real, targetReal);
+        await fsyncDir(path.dirname(targetReal));
+        await moveVersionSlug(node, to);
+        await patchMetaQuietly(node, { path: to, kind });
+      },
+      () => {
+        const row = store
+          ? store.updateNode(node.id, { path: to, kind, updatedAt: clock.now(), seq: store.nextSeq() })
+          : { ...node, path: to, kind };
+        if (source.stat.isDirectory()) movedChildren = rewriteDescendants(owner, from, to);
+        return row;
+      },
+    )));
+
+    for (const child of movedChildren) await patchMetaQuietly(child, { path: child.path });
+
+    await carryAssets(actor, owner, from, to, ctx, move);
+
+    events.emit('node-moved', { node: moved, from });
+    return moved;
+  }
+
+  // ---- copy --------------------------------------------------------------
+
+  async function copyTree(fromReal, toReal) {
+    const stat = await statIfExists(fromReal);
+    if (!stat) return;
+    if (!stat.isDirectory()) {
+      await copyFile(fromReal, toReal);
+      return;
+    }
+    await mkdirp(toReal);
+    for (const entry of await readdirIfExists(fromReal, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      await copyTree(path.join(fromReal, entry.name), path.join(toReal, entry.name));
+    }
+  }
+
+  async function copy({ actor, owner = '', from, to = null, ctx = {} }) {
+    const source = await resolveExisting(owner, from);
+    const node = nodes.resolve(owner, from);
+    authorize(actor, 'read', node, ctx);
+
+    const dir = path.dirname(to || from);
+    const parentReal = dir === '.' ? paths.realmRoot(owner) : await paths.resolveWrite(owner, dir);
+    await mkdirp(parentReal);
+    const free = await uniqueName(parentReal, path.basename(to || from));
+    const relPath = dir === '.' ? free : `${dir}/${free}`;
+
+    authorize(actor, 'write', nodes.resolve(owner, relPath), ctx);
+    const targetReal = await paths.resolveWrite(owner, relPath);
+
+    // Built under a hidden sibling name and renamed into place, so a crash
+    // leaves either nothing or the whole tree, never a partial one that
+    // `settle()` would read as finished because all it can see is that the
+    // destination exists. Same shape as publishInto's temp-then-link.
+    const staging = path.join(parentReal, `.makerclay-copy-${crypto.randomBytes(8).toString('hex')}`);
+
+    const created = await runOperation(
+      { kind: 'copy', nodeId: node.id, payload: { owner, from, to: relPath, staging } },
+      async () => {
+        try {
+          await copyTree(source.real, staging);
+          await rename(staging, targetReal);
+          await fsyncDir(path.dirname(targetReal));
+        } catch (error) {
+          await rmrf(staging);
+          throw error;
+        }
+        return await statIfExists(targetReal);
+      },
+      (stat) => {
+        const kind = stat?.isDirectory() ? 'dir' : nodes.kindFor(relPath);
+        return rowFor(owner, relPath, kind);
+      },
+    );
+
+    await carryAssets(actor, owner, from, relPath, ctx, copy);
+
+    events.emit('node-created', { node: created, copiedFrom: from });
+    return created;
+  }
+
+  // ---- trash / restore / purge -------------------------------------------
+
+  async function trash({ actor, owner = '', relPath, ctx = {} }) {
+    const source = await resolveExisting(owner, relPath);
+    const node = nodes.materialize(nodes.resolve(owner, relPath, {
+      kind: source.stat.isDirectory() ? 'dir' : undefined,
+    }));
+    authorize(actor, 'write', node, ctx);
+
+    const target = paths.trashPath(node.id, path.basename(relPath));
+    const at = clock.now();
+
+    let trashedChildren = [];
+    const gone = await locks.withLock(source.real, () => runOperation(
+      { kind: 'trash', nodeId: node.id, payload: { owner, from: relPath, to: target, fromReal: source.real } },
+      async () => {
+        await mkdirp(paths.dirs.trash);
+        await rename(source.real, target);
+        await fsyncDir(paths.dirs.trash);
+        await patchMetaQuietly(node, { trashed: true });
+      },
+      () => {
+        const row = nodes.tombstone(node, at);
+        if (store) {
+          trashedChildren = listDescendants(owner, relPath);
+          store.deleteSaveTokensForNode(node.id);
+          // The platform hard-deletes the record's auth row here, so a restored
+          // keyed record comes back public with no code. Soft-delete it WITH the
+          // node and restore it WITH the node (§15).
+          if (store.getRecordAuth(node.id)) store.updateRecordAuth(node.id, { deletedAt: at });
+          for (const child of trashedChildren) {
+            store.tombstone(child.id, at);
+            store.deleteSaveTokensForNode(child.id);
+            if (store.getRecordAuth(child.id)) store.updateRecordAuth(child.id, { deletedAt: at });
+          }
+        }
+        return row;
+      },
+    ));
+
+    // Every descendant's record, not just the operation's own node. The rows are
+    // tombstoned inside the commit above, but a rebuild trusts the RECORD, so a
+    // child whose record still says `trashed: false` comes back as a live row
+    // pointing at bytes that are in trash/. Same shape as move's descendant
+    // patch, and for the same reason.
+    for (const child of trashedChildren) await patchMetaQuietly(child, { trashed: true });
+
+    events.emit('node-trashed', { node: gone });
+    return gone;
+  }
+
+  async function restoreFromTrash({ actor, nodeId, ctx = {} }) {
+    assert(store, 'not-found', 'This host keeps no trash.');
+    const node = store.getNodeById(nodeId);
+    assert(node && node.deletedAt, 'not-found', 'Not in the trash.');
+    authorize(actor, 'write', { ...node, deletedAt: null }, ctx);
+
+    const source = paths.trashPath(node.id, path.basename(node.path));
+    assert(await statIfExists(source), 'not-found', 'The trashed bytes are gone.');
+
+    const dir = path.dirname(node.path);
+    const parentReal = dir === '.' ? paths.realmRoot(node.owner) : await paths.resolveWrite(node.owner, dir);
+    await mkdirp(parentReal);
+    const free = await uniqueName(parentReal, path.basename(node.path));
+    const relPath = dir === '.' ? free : `${dir}/${free}`;
+    const targetReal = await paths.resolveWrite(node.owner, relPath);
+
+    let restoredChildren = [];
+    const back = await runOperation(
+      { kind: 'restore', nodeId: node.id, payload: { owner: node.owner, from: source, to: relPath, toReal: targetReal } },
+      async () => {
+        await rename(source, targetReal);
+        await fsyncDir(path.dirname(targetReal));
+        await moveVersionSlug(node, relPath);
+        await patchMetaQuietly(node, { trashed: false, path: relPath });
+      },
+      () => {
+        const row = store.updateNode(node.id, {
+          path: relPath, deletedAt: null, updatedAt: clock.now(), seq: store.nextSeq(),
+        });
+        const auth = store.getRecordAuth(node.id);
+        if (auth?.deletedAt) store.updateRecordAuth(node.id, { deletedAt: null });
+        restoredChildren = listDescendants(node.owner, node.path).map((child) => {
+          const childAuth = store.getRecordAuth(child.id);
+          if (childAuth?.deletedAt) store.updateRecordAuth(child.id, { deletedAt: null });
+          return store.updateNode(child.id, {
+            path: `${relPath}${child.path.slice(node.path.length)}`,
+            deletedAt: null,
+            updatedAt: clock.now(),
+            seq: store.nextSeq(),
+          });
+        });
+        return row;
+      },
+    );
+
+    // The mirror of trash's cascade: the row half already rewrote every
+    // descendant's path, and the record has to learn both facts or the next
+    // rebuild puts them back in the trash they just came out of.
+    for (const child of restoredChildren) {
+      await patchMetaQuietly(child, { trashed: false, path: child.path });
+    }
+
+    events.emit('node-restored', { node: back });
+    return back;
+  }
+
+  async function purge({ actor, nodeId, ctx = {} }) {
+    assert(store, 'not-found', 'This host keeps no trash.');
+    const node = store.getNodeById(nodeId);
+    assert(node && node.deletedAt, 'not-found', 'Not in the trash.');
+    // The trash is the box owner's floor. `can` refuses the owner a WRITE on a
+    // tenant's document on purpose (someone else's instance is their document),
+    // but the bytes in here are no longer anyone's instance: they are storage
+    // the owner is being asked to keep. Without the admin arm a departed
+    // tenant's documents are unpurgeable forever, because the gate answers for
+    // an owner who no longer exists.
+    assert(
+      can(actor, 'admin', node, ctx) || can(actor, 'write', { ...node, deletedAt: null }, ctx),
+      'forbidden', 'You do not have permission to do that.',
+    );
+
+    const target = paths.trashPath(node.id, path.basename(node.path));
+    const children = listDescendants(node.owner, node.path);
+
+    await runOperation(
+      { kind: 'purge', nodeId: node.id, payload: { owner: node.owner, path: node.path, trash: target } },
+      async () => {
+        await rmrf(target);
+        for (const child of children) await versions.purge(child);
+        await versions.purge(node);
+      },
+      () => {
+        // The schema cascades shares, save tokens, collections, record_auth and
+        // the data-loss baseline off this one delete.
+        for (const child of children) store.deleteNode(child.id);
+        return store.deleteNode(node.id);
+      },
+    );
+
+    events.emit('node-purged', { node });
+    return { id: node.id, path: node.path };
+  }
+
+  // Reports what it actually removed. A swallowed refusal here told the owner
+  // their trash was empty while the bytes were still on disk, which is the one
+  // answer this lane must never give.
+  async function emptyTrash({ actor, ctx = {} }) {
+    if (!store) return { purged: 0, failed: [] };
+    const rows = store.listTrash().filter((row) => !row.path.includes('/'));
+    const failed = [];
+    let purged = 0;
+    for (const row of rows) {
+      try {
+        await purge({ actor, nodeId: row.id, ctx });
+        purged += 1;
+      } catch (error) {
+        logger.warn?.('[makerclay] could not purge', row.path, error?.message || error);
+        failed.push({ id: row.id, path: row.path, reason: error?.message || String(error) });
+      }
+    }
+    return { purged, failed };
+  }
+
+  // ---- flags -------------------------------------------------------------
+
+  const FLAG_OPS = { private: 'private', signups: 'signups', isolated: 'isolate' };
+
+  async function setFlag({ actor, owner = '', relPath, flag, value, ctx = {} }) {
+    assert(FLAG_OPS[flag], 'bad-request', `Unknown flag: ${flag}`);
+    assert(store, 'not-found', 'This host keeps no metadata.');
+    const node = nodes.materialize(nodes.resolve(owner, relPath));
+    authorize(actor, 'admin', node, ctx);
+
+    // Durable BEFORE the row, and allowed to throw. This is the direction that
+    // must never be lost: a flag that says private in the database and nothing
+    // on disk is a flag that a database loss turns back into public.
+    const flagValue = flag === 'isolated' && value === null ? null : !!value;
+    await versions.patchMeta(node, { [flag]: flagValue }, { create: true });
+
+    const updated = store.updateNode(node.id, {
+      [flag]: flagValue,
+      updatedAt: clock.now(),
+      seq: store.nextSeq(),
+    });
+    events.emit('node-updated', { node: updated, flag });
+    return updated;
+  }
+
+  return {
+    mkdir,
+    createDocument,
+    putFile,
+    putUpload,
+    move,
+    copy,
+    trash,
+    restoreFromTrash,
+    purge,
+    emptyTrash,
+    setFlag,
+    uniqueName,
+    TRASH_SEPARATOR,
+  };
+}