@makerclay/core 1.0.0

package/src/recovery/replay.js

@@ -0,0 +1,236 @@
+import path from 'upath';
+import { exists, rmrf } from '../util/fsx.js';
+
+// Finishing or unwinding the multi-step operations that were in flight when the
+// process died (§9.2 step 4).
+//
+// The whole method rests on one property of how ops.js writes: the filesystem
+// half of every operation is a SINGLE atomic rename. So which side of it the
+// crash landed on is a fact that can be READ OFF DISK, never a guess. The
+// journal says what was intended; the disk says whether it happened; this
+// module makes the database agree with the disk.
+//
+// When the two genuinely disagree in a way that cannot be resolved, the
+// operation is reported ambiguous and the host goes to recovery mode rather
+// than picking an answer.
+
+export function createReplay({ paths, store, nodes, versions, clock, logger = console }) {
+  const realFor = (owner, relPath) => path.join(paths.realmRoot(owner || ''), relPath);
+
+  async function recoverOperations() {
+    if (!store) return { completed: 0, unwound: 0, ambiguous: [] };
+    const pending = store.listOperations();
+    if (!pending.length) return { completed: 0, unwound: 0, ambiguous: [] };
+
+    let completed = 0;
+    let unwound = 0;
+    const ambiguous = [];
+
+    for (const op of pending) {
+      try {
+        const verdict = await settle(op);
+        if (verdict === 'completed') completed += 1;
+        else if (verdict === 'unwound') unwound += 1;
+        else ambiguous.push({ id: op.id, kind: op.kind, payload: op.payload });
+        if (verdict !== 'ambiguous') store.deleteOperation(op.id);
+      } catch (error) {
+        logger.error?.('[makerclay] recovery failed for operation', op.id, error?.message || error);
+        ambiguous.push({ id: op.id, kind: op.kind, payload: op.payload, error: error?.message || String(error) });
+      }
+    }
+
+    if (completed || unwound || ambiguous.length) {
+      logger.warn?.(
+        `[makerclay] recovered ${completed} interrupted operation(s), unwound ${unwound}` +
+        (ambiguous.length ? `, ${ambiguous.length} need attention` : ''),
+      );
+    }
+    return { completed, unwound, ambiguous };
+  }
+
+  async function settle(op) {
+    const { kind, payload = {}, nodeId } = op;
+    const owner = payload.owner ?? '';
+
+    if (kind === 'mkdir' || kind === 'create' || kind === 'copy') {
+      // Nothing was destroyed either way. If the bytes landed the scanner will
+      // adopt them a moment from now; if they did not, the plan is just noise.
+      //
+      // A copy that died before its rename left its staging tree behind. It is
+      // dot-prefixed so nothing lists it and the scanner skips it, but it is
+      // still the whole tree's worth of bytes.
+      if (payload.staging) await rmrf(payload.staging);
+      return (await exists(realFor(owner, payload.path ?? payload.to))) ? 'completed' : 'unwound';
+    }
+
+    if (kind === 'move') {
+      const from = payload.fromReal || realFor(owner, payload.from);
+      const to = payload.toReal || realFor(owner, payload.to);
+      const [hasFrom, hasTo] = [await exists(from), await exists(to)];
+      if (hasTo && !hasFrom) {
+        if (!finishMove(op, owner, payload)) return 'ambiguous';
+        await repairMoveRecord(op, owner, payload);
+        return 'completed';
+      }
+      if (hasFrom && !hasTo) return 'unwound';
+      return 'ambiguous';
+    }
+
+    if (kind === 'trash') {
+      const from = payload.fromReal || realFor(owner, payload.from);
+      const [hasFrom, hasTrash] = [await exists(from), await exists(payload.to)];
+      if (hasTrash && !hasFrom) {
+        const children = descendants(owner, payload.from);
+        if (!finishTrash(op, owner, payload)) return 'ambiguous';
+        await patchMetaQuietly(store.getNodeById(op.nodeId), { trashed: true });
+        for (const child of children) await patchMetaQuietly(child, { trashed: true });
+        return 'completed';
+      }
+      if (hasFrom && !hasTrash) return 'unwound';
+      return 'ambiguous';
+    }
+
+    if (kind === 'restore') {
+      const to = payload.toReal || realFor(owner, payload.to);
+      const [hasTrash, hasTo] = [await exists(payload.from), await exists(to)];
+      if (hasTo && !hasTrash) {
+        if (!finishRestore(op, owner, payload)) return 'ambiguous';
+        await patchMetaQuietly(store.getNodeById(op.nodeId), { trashed: false, path: payload.to });
+        for (const child of descendants(owner, payload.to)) {
+          await patchMetaQuietly(child, { trashed: false, path: child.path });
+        }
+        return 'completed';
+      }
+      if (hasTrash && !hasTo) return 'unwound';
+      return 'ambiguous';
+    }
+
+    if (kind === 'purge') {
+      if (await exists(payload.trash)) return 'unwound';
+      // Captured before the transaction, because after it the rows are gone and
+      // `versions.purge` resolves the directory by node id.
+      const orphaned = nodeId
+        ? [...descendants(owner, payload.path), store.getNodeById(nodeId)].filter(Boolean)
+        : [];
+      const done = finishPurge(nodeId, owner, payload);
+      // The ordinary purge lane removes the history along with the bytes. A
+      // purge interrupted after the bytes went and before the rows did used to
+      // leave the history orphaned under versions/, which was harmless while
+      // nothing read it. It stops being harmless the moment the overlay
+      // reconciles against durable records: the orphan still says trashed:true,
+      // so the next boot reads it as a live trashed document and puts the row
+      // back.
+      if (done) for (const row of orphaned) await versions.purge(row);
+      return done ? 'completed' : 'unwound';
+    }
+
+    return 'ambiguous';
+  }
+
+  function descendants(owner, prefix) {
+    return store.listNodes({ owner, prefix: `${prefix}/`, includeDeleted: true });
+  }
+
+  // finish* puts the ROW right. The durable record is the other half, and the
+  // kill that stranded this operation could just as easily have landed between
+  // the rename and the record write, so the same patch ops.js makes inline is
+  // made here before the intent is thrown away. Without it the record keeps the
+  // old path, or a stale trashed marker, and a later database loss rebuilds the
+  // overlay from that.
+  //
+  // Best-effort for the same reason as ops.js's patchMetaQuietly: a repair that
+  // throws must not re-brick the boot it is part of.
+  async function patchMetaQuietly(node, patch) {
+    if (!node) return;
+    try {
+      await versions.patchMeta(node, patch);
+    } catch (error) {
+      logger.warn?.('[makerclay] could not update the durable record:', error?.message || error);
+    }
+  }
+
+  async function repairMoveRecord(op, owner, payload) {
+    const row = store.getNodeById(op.nodeId);
+    if (!row) return;
+    // Read back after finishMove, so `row.kind` is the recomputed one and the
+    // record cannot end up describing the file as something the row does not.
+    await patchMetaQuietly(row, { path: payload.to, kind: row.kind });
+    // A directory move rewrote its descendants too, the way ops.move patches
+    // `movedChildren`. Read back at the new prefix, so these are the rows
+    // finishMove just wrote.
+    for (const child of descendants(owner, payload.to)) {
+      await patchMetaQuietly(child, { path: child.path });
+    }
+  }
+
+  function finishMove(op, owner, payload) {
+    const row = store.getNodeById(op.nodeId);
+    if (!row) return true;
+    // A rename can change what the file IS, and kind is what decides both the
+    // serve lane and the sandbox, so it is recomputed here exactly as ops.move
+    // recomputes it rather than carried over.
+    const kind = row.kind === 'dir' ? 'dir' : nodes.kindFor(payload.to);
+    return store.tx(() => {
+      for (const child of descendants(owner, payload.from)) {
+        store.updateNode(child.id, {
+          path: `${payload.to}${child.path.slice(payload.from.length)}`,
+          updatedAt: clock.now(),
+          seq: store.nextSeq(),
+        });
+      }
+      store.updateNode(row.id, { path: payload.to, kind, updatedAt: clock.now(), seq: store.nextSeq() });
+      return true;
+    });
+  }
+
+  function finishTrash(op, owner, payload) {
+    const row = store.getNodeById(op.nodeId);
+    if (!row) return true;
+    const at = clock.now();
+    return store.tx(() => {
+      for (const child of descendants(owner, payload.from)) {
+        store.tombstone(child.id, at);
+        store.deleteSaveTokensForNode(child.id);
+        if (store.getRecordAuth(child.id)) store.updateRecordAuth(child.id, { deletedAt: at });
+      }
+      store.tombstone(row.id, at);
+      store.deleteSaveTokensForNode(row.id);
+      if (store.getRecordAuth(row.id)) store.updateRecordAuth(row.id, { deletedAt: at });
+      return true;
+    });
+  }
+
+  function finishRestore(op, owner, payload) {
+    const row = store.getNodeById(op.nodeId);
+    if (!row) return true;
+    return store.tx(() => {
+      for (const child of descendants(owner, row.path)) {
+        store.updateNode(child.id, {
+          path: `${payload.to}${child.path.slice(row.path.length)}`,
+          deletedAt: null,
+          updatedAt: clock.now(),
+          seq: store.nextSeq(),
+        });
+        const childAuth = store.getRecordAuth(child.id);
+        if (childAuth?.deletedAt) store.updateRecordAuth(child.id, { deletedAt: null });
+      }
+      store.updateNode(row.id, {
+        path: payload.to, deletedAt: null, updatedAt: clock.now(), seq: store.nextSeq(),
+      });
+      const auth = store.getRecordAuth(row.id);
+      if (auth?.deletedAt) store.updateRecordAuth(row.id, { deletedAt: null });
+      return true;
+    });
+  }
+
+  function finishPurge(nodeId, owner, payload) {
+    if (!nodeId) return true;
+    return store.tx(() => {
+      for (const child of descendants(owner, payload.path)) store.deleteNode(child.id);
+      store.deleteNode(nodeId);
+      return true;
+    });
+  }
+
+  return { recoverOperations };
+}

package/src/recovery-ui.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'upath';
+import { fileURLToPath } from 'node:url';
+import { readFileTextIfExists, statIfExists } from './util/fsx.js';
+import { renderTemplate } from './ui.js';
+import { wrap } from './util/express.js';
+
+// Recovery mode (§18.3).
+//
+// When migrations fail, the database fails its integrity check, or the
+// operations journal is ambiguous, the host refuses to serve documents at all: a
+// half-started server sitting on uncertain privacy metadata is worse than a
+// clearly refused one. This is what it serves instead.
+//
+// Three rules, and each is the reason the mode is worth having:
+//
+//   - The operator is at the machine. Nobody on the network gets a listing of
+//     every file plus a raw download lane just because the database is unhappy.
+//     Loopback alone does not say that: the deploy configs this repo ships
+//     `proxy_pass http://127.0.0.1`, so behind either of them every request on
+//     the internet arrives from 127.0.0.1. The boot key is what actually says
+//     it, because it is printed to the server's own console and nowhere else.
+//   - It never serves a document. Every download is octet-stream, attachment,
+//     nosniff. A page whose privacy metadata we do not currently trust must not
+//     render in a browser at this origin.
+//   - It reads and never writes. The whole point is that nothing has decided
+//     what the truth is yet.
+//
+// Its page comes from the PACKAGE, never from `<data>/ui/`: in recovery mode the
+// first-run copy into the data directory has not happened, and one of the things
+// that can be broken is exactly that directory.
+
+const PACKAGE_UI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'ui');
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+export function isLoopback(req) {
+  const address = req.socket?.remoteAddress || req.connection?.remoteAddress || '';
+  return LOOPBACK.has(String(address));
+}
+
+// files/ and tenants/ are the documents; versions/ is their history; records/ is
+// collection submissions, the one part of a backup nobody can re-create by hand.
+const DOWNLOADABLE_DIRS = ['files', 'tenants', 'versions', 'trash', 'records'];
+const DOWNLOADABLE_FILES = { db: 'makerclay.db', config: 'config.json' };
+
+function walk(root, base = '', out = [], budget = { left: 5000 }) {
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(root, base), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (budget.left <= 0) return out;
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      walk(root, rel, out, budget);
+    } else if (entry.isFile()) {
+      budget.left -= 1;
+      let size = null;
+      try { size = fs.statSync(path.join(root, rel)).size; } catch { size = null; }
+      out.push({ path: rel, size });
+    }
+  }
+  return out;
+}
+
+
+export function mountRecoveryUi({ app, paths, store, recovery, stateOf}) {
+  const data = paths.dirs.data;
+  const key = crypto.randomBytes(16).toString('hex');
+
+  function notFound(res) {
+    // Not a 403: to anyone without the key there is nothing here to find.
+    return res.status(404).json({ ok: false, code: 'not-found', msg: 'Not found' });
+  }
+
+  function keyMatches(given) {
+    const offered = Buffer.from(String(given ?? ''));
+    const expected = Buffer.from(key);
+    return offered.length === expected.length && crypto.timingSafeEqual(offered, expected);
+  }
+
+  function guard(req, res, next) {
+    // Outside recovery mode there is no recovery UI at all: the route falls
+    // through and `/_/recover` is an ordinary 404.
+    if (stateOf().state !== 'recover') return next('route');
+    if (!isLoopback(req)) return notFound(res);
+    if (!keyMatches(req.query.key ?? req.get('x-recovery-key'))) return notFound(res);
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    // The key is in the URL, so keep it out of anything that follows a link out.
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    return next();
+  }
+
+  // Everything the doctor report is built from, computed defensively: in this
+  // mode any one of these calls is allowed to be the thing that is broken.
+  async function report() {
+    const state = stateOf();
+    const safely = async (label, fn) => {
+      try { return await fn(); } catch (error) { return { error: `${label}: ${error?.message || error}` }; }
+    };
+    return {
+      state: state.state,
+      reason: state.reason ?? null,
+      error: state.error ?? null,
+      ambiguous: state.ambiguous ?? [],
+      data,
+      counts: await safely('counts', () => ({
+        nodes: store ? store.listAllNodes().length : 0,
+        trash: store ? store.listTrash().length : 0,
+        operations: store ? store.listOperations().length : 0,
+      })),
+      operations: await safely('operations', () => (store ? store.listOperations() : [])),
+      integrity: await safely('integrity', () => (store ? store.integrityCheck() : ['no database'])),
+      records: await safely('records', async () => (await recovery.readAllMeta()).length),
+      artifacts: Object.entries(DOWNLOADABLE_FILES).map(([key, name]) => {
+        const file = path.join(data, name);
+        const exists = fs.existsSync(file);
+        return { key, name, exists, size: exists ? fs.statSync(file).size : null };
+      }),
+    };
+  }
+
+  app.get('/_/recover', guard, wrap(async (req, res) => {
+    const source = await readFileTextIfExists(path.join(PACKAGE_UI, 'recovery.html'));
+    if (source == null) {
+      return res.status(500).type('text/plain').send('Recovery page missing. Run `makerclay doctor`.');
+    }
+    const state = stateOf();
+    res.type('text/html; charset=utf-8');
+    return res.send(renderTemplate(source, { reason: state.reason || 'unknown', data }));
+  }));
+
+  app.get('/_/recover/report', guard, wrap(async (req, res) => res.json({ ok: true, ...(await report()) })));
+
+  app.get('/_/recover/tree', guard, (req, res) => {
+    const trees = DOWNLOADABLE_DIRS
+      .filter((dir) => fs.existsSync(path.join(data, dir)))
+      .map((dir) => ({ dir, files: walk(path.join(data, dir)).map((f) => ({ ...f, path: `${dir}/${f.path}` })) }));
+    return res.json({ ok: true, trees });
+  });
+
+  // The download lane. `attachment` + octet-stream is what keeps the promise
+  // that this mode never serves a document: the browser saves the bytes, it
+  // does not run them.
+  app.get('/_/recover/raw', guard, wrap(async (req, res) => {
+    const wanted = String(req.query.path || '');
+    // `Object.hasOwn`, because a plain lookup finds `constructor` and `toString`
+    // on the prototype and hands them to path.join as the filename.
+    const named = Object.hasOwn(DOWNLOADABLE_FILES, wanted) ? DOWNLOADABLE_FILES[wanted] : null;
+    const lexical = path.resolve(path.join(data, named || wanted));
+
+    // The allowlist is read off the RESOLVED path, never off what was asked
+    // for: `files/../config.json` starts with an allowed directory name and
+    // means something else entirely.
+    const inside = lexical.startsWith(`${data}/`);
+    const top = inside ? lexical.slice(data.length + 1).split('/')[0] : '';
+    if (!inside || !(named || DOWNLOADABLE_DIRS.includes(top))) return notFound(res);
+
+    let real;
+    try {
+      real = path.resolve(fs.realpathSync(lexical));
+    } catch {
+      return notFound(res);
+    }
+    // A symlink out of the data directory is the one way this lane could hand
+    // over something that is not ours, so it is checked after resolution.
+    const stat = real === lexical ? await statIfExists(real) : null;
+    if (!stat?.isFile()) return notFound(res);
+
+    res.setHeader('Content-Type', 'application/octet-stream');
+    res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+    // A filename is whatever the filesystem allowed, including a newline, and a
+    // newline in a header value throws rather than being escaped.
+    res.setHeader('Content-Disposition',
+      `attachment; filename="${path.basename(real).replace(/[^\w.-]+/g, '_')}"`);
+    return res.sendFile(real);
+  }));
+
+  return { report, isLoopback, key, url: `/_/recover?key=${key}` };
+}

package/src/recovery.js

@@ -0,0 +1,30 @@
+import { createReplay } from './recovery/replay.js';
+import { createOverlay } from './recovery/overlay.js';
+
+// What happens between `kill -9` and the next boot.
+//
+// Two independent jobs, both run before the host serves a request, and each in
+// its own file because they answer different questions from different evidence:
+//
+//   recovery/replay.js    finish or unwind the multi-step ops that were in
+//                         flight (§9.2 step 4). Reads the journal, then reads
+//                         the disk to see which side of the single atomic
+//                         rename the crash landed on.
+//
+//   recovery/overlay.js   the store is an overlay, so losing it must not lose
+//                         privacy or tenancy (§6.3). Reads the durable records
+//                         under versions/, and rebuilds the database from them.
+//
+// They share no state, and neither calls the other. What they do share is the
+// one rule: when the evidence is genuinely ambiguous, never guess. A clear
+// degraded mode beats a half-working dashboard sitting on top of uncertain
+// privacy metadata.
+//
+// boot.js runs them in order — replay first, because an operation left half
+// applied would otherwise be assessed as if it were the settled truth.
+
+export function createRecovery({ paths, store, nodes, versions, clock, logger = console }) {
+  const replay = createReplay({ paths, store, nodes, versions, clock, logger });
+  const overlay = createOverlay({ paths, store, nodes, clock, logger });
+  return { ...replay, ...overlay };
+}

package/src/requests.js

@@ -0,0 +1,73 @@
+import { PathError } from './paths.js';
+import { can } from './auth/can.js';
+import { jsonError } from './json-errors.js';
+import { rawDocumentPath, resolveDocumentHref } from './spec/wire.js';
+
+// Turning a request into a node, and refusing when it cannot.
+//
+// These travelled together through every route as separate arguments, which made
+// them look like unrelated passengers rather than one service with one rule. The
+// rule is the important part, and it is easier to hold in one place than to
+// re-derive at each call site:
+//
+//   A read refusal is a 404, shaped exactly like a missing document.
+//
+// Never a 403. A 403 tells a stranger that the document exists, which is the
+// whole disclosure a private document is trying to avoid, so "you may not read
+// this" and "there is nothing here" have to be indistinguishable from outside.
+// That is why `resolveTarget` returns null for both and never throws: a
+// traversal attempt and a typo get the same answer.
+//
+// It still catches PathError rather than calling `paths.tryResolveRead`, because
+// what it wraps is `serve.resolveForRead`, which resolves a path AND runs the
+// gate. Only a refusal from the path half is ordinary; a HostError raised by the
+// gate is a real answer and must reach the client.
+
+export function createRequestResolution({ serve, store, clock, gateCtx }) {
+  function notFoundDocument(req, res) {
+    if (req.path.startsWith('/_/') || req.accepts(['html', 'json']) === 'json') {
+      return jsonError(res, 'not-found', 'Not found');
+    }
+    res.status(404).type('text/html').send('<!DOCTYPE html><title>Not found</title><h1>Not found</h1>');
+    return undefined;
+  }
+
+  function resolveHref(href) {
+    const { owner, rest } = serve.parseRealm(rawDocumentPath(href));
+    return { owner, relPath: resolveDocumentHref(rest) };
+  }
+
+  async function resolveTarget(actor, urlPathOrHref, action = 'read') {
+    const urlPath = rawDocumentPath(urlPathOrHref);
+    try {
+      const found = await serve.resolveForRead(actor, urlPath);
+      if (!found) return null;
+      if (action !== 'read' && !can(actor, action, found.node, gateCtx)) return null;
+      return { ...found, actor };
+    } catch (error) {
+      if (error instanceof PathError) return null;
+      throw error;
+    }
+  }
+
+  async function resolveSaveToken(rawToken) {
+    if (!store || !rawToken) return null;
+    const record = store.getSaveToken(String(rawToken));
+    if (!record || record.expiresAt <= clock.now()) return null;
+    const node = store.getNodeById(record.nodeId);
+    if (!node) return null;
+    if (record.shareHash) {
+      const share = store.getShare(record.shareHash);
+      if (!share || share.revokedAt || (share.expiresAt && share.expiresAt <= clock.now())) return null;
+    }
+    // Defence in depth behind revocation: a save token is a bearer credential in
+    // a URL, and this is the one place every use of one passes through.
+    if (record.principal?.startsWith('tenant:')) {
+      const tenant = store.getTenant(record.principal.slice('tenant:'.length));
+      if (!tenant || tenant.disabledAt) return null;
+    }
+    return { nodeId: record.nodeId, grantKind: record.grantKind, node, principal: record.principal };
+  }
+
+  return { notFoundDocument, resolveHref, resolveTarget, resolveSaveToken };
+}

package/src/routes/meta.js

@@ -0,0 +1,62 @@
+import { hostMeta, documentBlock } from '../spec/meta.js';
+import { documentUrlHeader, documentEtag } from '../spec/wire.js';
+import { readFileTextIfExists } from '../util/fsx.js';
+import { wrap } from '../util/express.js';
+
+// spec §5 discovery.
+//
+// Host scope is never gated and is CORS-open: the caller is a page a person
+// just loaded, often anonymously, and this is the only place a client is
+// permitted to learn what the host supports.
+
+export function mountMetaRoutes({
+  system, config, serve, gateCtx, resolveTarget, resolveSaveToken, tryResolveRead,
+}) {
+  async function metaResponse(req, res, { node, real, actor }) {
+    // Host scope is CORS-open, unless a tighter rule already answered: the
+    // token lane below pins this to `null`, and widening it back to `*` here
+    // would hand any origin a document block it holds no token for.
+    if (!res.getHeader('Access-Control-Allow-Origin')) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+    }
+    res.setHeader('Vary', 'Origin');
+    const body = hostMeta(config.capabilities);
+    if (node && real) {
+      const stored = await readFileTextIfExists(real);
+      if (stored != null) {
+        body.document = documentBlock({
+          node,
+          etag: documentEtag(stored),
+          actor,
+          ctx: gateCtx,
+          limits: config.limits,
+          isolated: serve.isolationFor(node),
+          capabilities: config.capabilities,
+        });
+      }
+    }
+    return res.json(body);
+  }
+
+  system.options('/meta', (req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'Document-URL, Page-URL, If-Match');
+    res.setHeader('Vary', 'Origin');
+    res.status(204).end();
+  });
+
+  system.get('/meta', wrap(async (req, res) => {
+    const href = documentUrlHeader(req);
+    if (!href) return metaResponse(req, res, {});
+    const found = await resolveTarget(req.actor, href, 'read');
+    return metaResponse(req, res, found || {});
+  }));
+
+  system.get('/meta/:token', wrap(async (req, res) => {
+    const grant = await resolveSaveToken(req.params.token);
+    if (!grant) return metaResponse(req, res, {});
+    const actor = { ...req.actor, grants: { ...req.actor.grants, saveToken: grant } };
+    const real = await tryResolveRead(grant.node.owner, grant.node.path);
+    return metaResponse(req, res, real ? { node: grant.node, real, actor } : {});
+  }));
+}