@makerclay/core 1.0.0

package/src/routes/read.js

@@ -0,0 +1,105 @@
+import path from 'upath';
+import { jsonError } from '../json-errors.js';
+import { readFileText } from '../util/fsx.js';
+import { extractData, parseExtractionRules } from '../derived/data-extractor.js';
+import { applySecurityHeaders } from '../tenants/isolation.js';
+import { wrap } from '../util/express.js';
+
+// Every lane that hands a node's bytes to a caller: `/_/download`, `/_/api/*`,
+// and the document lane itself, whose `?data=` half is the second address of the
+// same extraction feature `/_/api` serves.
+//
+// Together in one file because the rules they share are the ones that go wrong
+// when they drift. `features.dataApi` gates both extraction halves; every lane
+// that carries node bytes says the same thing about the node with
+// `applySecurityHeaders`. Splitting them across files is how one half ends up
+// answering after the flag was turned off.
+//
+// Two mount points, because one group lives under the host's `/_` prefix and the
+// document lane is the fall-through that has to be registered after it.
+
+// An SVG is a document that browsers happen to draw. Navigate to one directly
+// and its script runs on this origin; pull the same file through an `img` tag,
+// a CSS background, or any other image load and it cannot. The attachment
+// disposition keeps exactly that split: every way a page embeds an SVG still
+// works, and the one way it could execute becomes a download instead.
+//
+// Not left to the sandbox header, which would also stop it: that header is
+// absent under `isolation: 'off'`, a configuration this host supports, and
+// uploads must not stop being inert because someone changed an unrelated
+// setting. This one is unconditional.
+function applyInertImageHeaders(res, relPath) {
+  if (/\.svgz?$/i.test(relPath)) res.setHeader('Content-Disposition', 'attachment');
+}
+
+export function mountReadRoutes({ system, config, serve, derived, resolveTarget }) {
+  system.get('/download', wrap(async (req, res) => {
+    const raw = req.query.path;
+    if (typeof raw !== 'string' || !raw) return jsonError(res, 'bad-request', 'path required.');
+    const found = await resolveTarget(req.actor, raw, 'read');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+    // The attachment disposition is what stops these bytes rendering, but this
+    // lane carries node bytes like every other, so it says the same thing about
+    // the node as every other lane does.
+    applySecurityHeaders(res, serve.isolationFor(found.node));
+    res.setHeader('Content-Disposition',
+      `attachment; filename="${path.basename(found.node.path).replace(/[^\w.-]+/g, '_')}"`);
+    res.sendFile(found.real);
+    return undefined;
+  }));
+
+  system.get(/^\/api\/(.+)$/, wrap(async (req, res) => {
+    if (config.features.dataApi === false) return jsonError(res, 'not-found', 'Not found');
+    const found = await resolveTarget(req.actor, `/${req.params[0]}`, 'read');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+    const cached = await derived.readSidecar(found.node, found.real);
+    if (cached !== null) return res.type('application/json').send(cached);
+    const html = await readFileText(found.real);
+    await derived.writeSidecar(found.node, html, found.real);
+    const fresh = await derived.readSidecar(found.node, found.real);
+    if (fresh === null) {
+      return jsonError(res, 'not-found', 'This page has no rules tag with data-rules-name~="api".');
+    }
+    return res.type('application/json').send(fresh);
+  }));
+}
+
+export function mountDocumentLane({ app, config, serve, events, resolveTarget, notFoundDocument }) {
+  app.get(/.*/, wrap(async (req, res, next) => {
+    if (req.method !== 'GET') return next();
+    const found = await resolveTarget(req.actor, req.path, 'read');
+    if (!found) return notFoundDocument(req, res);
+
+    if (req.query.data !== undefined) {
+      // The same switch as `/_/api`. Extraction is one feature with two
+      // addresses, and gating only the dedicated one meant turning the data API
+      // off left this half answering, which is not what anyone reading the flag
+      // expects.
+      if (config.features.dataApi === false) return notFoundDocument(req, res);
+      const html = await readFileText(found.real);
+      try {
+        const rules = parseExtractionRules(String(req.query.data));
+        return res.json(extractData(html, rules));
+      } catch (error) {
+        return jsonError(res, 'bad-request', `Invalid extraction rules: ${error.message}`);
+      }
+    }
+
+    if (found.node.kind !== 'doc') {
+      applySecurityHeaders(res, serve.isolationFor(found.node));
+      applyInertImageHeaders(res, found.node.path);
+      return res.sendFile(found.real);
+    }
+
+    const rendered = await serve.renderDocument({
+      actor: req.actor, owner: found.owner, node: found.node, real: found.real,
+    });
+    applySecurityHeaders(res, rendered.isolated);
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    events.emit('node-served', { node: rendered.node, actor: req.actor });
+    return res.send(rendered.body);
+  }));
+
+  app.use((req, res) => notFoundDocument(req, res));
+}

package/src/routes/save.js

@@ -0,0 +1,102 @@
+import express from 'express';
+import { can } from '../auth/can.js';
+import { jsonError, sendJson } from '../json-errors.js';
+import { documentUrlHeader, ifMatchHeader, saveTrigger, readSaveBody } from '../spec/wire.js';
+import { wrap } from '../util/express.js';
+
+// The save lane.
+//
+// Two addresses into one `handleSave`, and the difference between them is only
+// how the caller proves it may write: a cookie on `/save`, a save token on
+// `/save/:token`. Everything after that point is the same code, which is what
+// keeps the quota, the sandbox rule and the version record from drifting apart
+// between the two.
+
+export function mountSaveRoutes({
+  system, config, nodes, serve, tenants, replace, gateCtx,
+  resolveHref, resolveSaveToken, track,
+}) {
+  const saveJson = express.json({ limit: config.limits.saveBytes, type: ['application/json', '+json'] });
+  const saveText = express.text({ type: () => true, limit: config.limits.saveBytes });
+
+  async function handleSave(req, res, grant = null) {
+    const parsed = readSaveBody(req);
+    if (!parsed.ok) return jsonError(res, parsed.code, parsed.msg);
+    if (typeof parsed.content !== 'string') {
+      return jsonError(res, 'invalid-document', 'Expected the document as text.');
+    }
+
+    let owner = '';
+    let relPath = null;
+    let actor = req.actor;
+
+    if (grant) {
+      owner = grant.node.owner;
+      relPath = grant.node.path;
+      actor = { ...req.actor, grants: { ...req.actor.grants, saveToken: grant } };
+    } else {
+      const href = documentUrlHeader(req);
+      if (!href) {
+        return jsonError(res, 'bad-request', 'Document-URL header required.');
+      }
+      const target = resolveHref(href);
+      owner = target.owner;
+      relPath = target.relPath;
+
+      // §16.6. The cookie lane is closed to a sandboxed TENANT document. It runs
+      // under an opaque origin and cannot send a cookie at all, so a
+      // cookie-authenticated save of one came from something else on this
+      // origin; requiring the token keeps that true even in a browser that
+      // ignores the CSP.
+      //
+      // Scoped to tenant realms on purpose. Under the default `untrusted` mode
+      // every file the owner drops into their own folder is sandboxed too, and
+      // closing the cookie lane there would mean rsyncing a file in silently
+      // costs you the ability to edit it in your own browser. The threat §16.1
+      // states is the tenant, and this is where it lives.
+      // Checked only for someone who could otherwise write it. Refusing before
+      // the gate would answer 403-with-a-reason to a tenant probing someone
+      // else's realm, and that distinguishes "exists but sandboxed" from
+      // "nothing here", which is the leak read refusals are 404 to avoid.
+      const node = nodes.resolve(owner, relPath);
+      if (owner && can(req.actor, 'write', node, gateCtx) && serve.isolationFor(node)) {
+        return jsonError(
+          res, 'read-only',
+          'This document runs in a sandbox, so it saves with its token rather than with a cookie.',
+        );
+      }
+    }
+
+    // Before the kernel, not after: a quota that only notices once the bytes are
+    // on disk is an audit log, not a limit.
+    if (owner && tenants.enabled) {
+      tenants.checkQuota(owner, { relPath, bytes: Buffer.byteLength(parsed.content, 'utf8') });
+    }
+
+    const result = await replace({
+      actor,
+      owner,
+      relPath,
+      bytes: parsed.content,
+      ifMatch: ifMatchHeader(req),
+      trigger: saveTrigger(req),
+      senderId: req.headers['x-sender-id'] || null,
+      ctx: gateCtx,
+    });
+
+    // Three keys the spec names plus msgType, so clayjs (msg/msgType) and a
+    // spec client (code/etag) both read a complete answer. [wire-compat]
+    sendJson(res, 200, { msg: result.msg, msgType: result.msgType, etag: result.etag });
+    if (owner && tenants.enabled) tenants.recordUsage(owner);
+    track(result.derived());
+    return undefined;
+  }
+
+  system.post('/save', saveJson, saveText, wrap((req, res) => handleSave(req, res)));
+
+  system.post('/save/:token', saveJson, saveText, wrap(async (req, res) => {
+    const grant = await resolveSaveToken(req.params.token);
+    if (!grant) return jsonError(res, 'unauthorized', 'This save token is not valid.');
+    return handleSave(req, res, grant);
+  }));
+}

package/src/routes/sync.js

@@ -0,0 +1,118 @@
+import express from 'express';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { documentUrlHeader } from '../spec/wire.js';
+import { hasHtmlRoot } from '../documents/format-html.js';
+import { stripRootAttrs } from '../documents/root-attrs.js';
+import { EPHEMERAL_ATTRS } from '../documents/replace.js';
+import { wrap } from '../util/express.js';
+
+// spec §10 relay.
+//
+// NEVER writes disk. A `snapshot` fans out to the other editors on the live
+// lane; a `document` fans out to viewers on the saved lane.
+
+// The v2 device-sync lane. Reserved NOW so a v1 host never accidentally serves
+// something else from these paths and a v2 client can tell "not implemented yet"
+// from "wrong kind of server".
+const RESERVED_SYNC_PATHS = ['nodes', 'status', 'stream', 'control'];
+
+export function mountSyncRoutes({
+  system, config, liveSync, nodes, gateCtx, resolveHref, resolveSaveToken,
+}) {
+  const syncJson = express.json({ limit: config.limits.saveBytes });
+
+  async function handleRelay(req, res) {
+    if (!liveSync) return jsonError(res, 'not-found', 'This host does not advertise sync.');
+    const href = documentUrlHeader(req);
+    if (!href) return jsonError(res, 'bad-request', 'Document-URL header required.');
+    const { owner, relPath } = resolveHref(href);
+
+    const body = req.body || {};
+    const snapshot = typeof body.snapshot === 'string' ? body.snapshot
+      : typeof body.html === 'string' ? body.html : null;
+    const document = typeof body.document === 'string' ? body.document : null;
+    if (snapshot == null && document == null) {
+      return jsonError(res, 'bad-request', 'Expected {snapshot} or {document}.');
+    }
+
+    // The same grant the GET half takes. Both halves of one §10 address have to
+    // agree about what authenticates a caller: while only the receiver read it,
+    // a sandboxed document could subscribe to updates and never send one.
+    let actor = req.actor;
+    const token = req.query.token || req.body?.token;
+    if (token) {
+      const grant = await resolveSaveToken(String(token));
+      if (grant) actor = { ...actor, grants: { ...actor.grants, saveToken: grant } };
+    }
+
+    const node = nodes.resolve(owner, relPath);
+    const lane = document != null ? 'saved' : 'live';
+    const action = lane === 'saved' ? 'read' : 'write';
+    if (!can(actor, action, node, gateCtx)) {
+      return jsonError(res, 'not-found', 'Not found');
+    }
+    if (document != null && !hasHtmlRoot(document)) {
+      return jsonError(res, 'invalid-document', 'Not a complete HTML document.');
+    }
+
+    // Serve-time machinery, never a document's own bytes — the same rule
+    // replace.js applies on save. A relay frame goes to another person's browser,
+    // so a credential riding along would be minted for one principal and land on
+    // another's root.
+    const relayed = stripRootAttrs(document ?? snapshot, EPHEMERAL_ATTRS);
+
+    const delivered = liveSync.broadcast(
+      owner, relPath,
+      { html: relayed, sender: body.sender || req.headers['x-sender-id'] || null, identityMap: body.identityMap },
+      { lane },
+    );
+    return res.json({ ok: true, lane, delivered });
+  }
+
+  // Spec §10: one address, POST to send and GET to receive. The /_/live-sync/*
+  // aliases are kept permanently alongside it. They were removed on 2026-08-21 on the
+  // reading that nothing outside our own clients speaks them; that turned out to be
+  // false. A saved document is a frozen client: the Collection dashboard opens
+  // /_/live-sync/stream from inline page script, so every dashboard ever minted names
+  // that path and no library update can reach it, and hyperclayjs hardcodes both.
+  // The exact routes only; the reserved device-lane subpaths below are unaffected,
+  // because express distinguishes a route from its subpaths.
+  system.post(['/sync', '/live-sync/save'], syncJson, wrap(handleRelay));
+
+  system.get(['/sync', '/live-sync/stream'], wrap(async (req, res) => {
+    if (!liveSync) return jsonError(res, 'not-found', 'This host does not advertise sync.');
+    // document-url is the spec spelling and wins; page-url is the pre-spec one,
+    // still read because a host being lenient about how it is addressed costs
+    // nothing and a stream that silently 404s is hard to diagnose.
+    const href = req.query['document-url'] || req.query['page-url'] || documentUrlHeader(req);
+    if (!href) return jsonError(res, 'bad-request', 'document-url parameter required.');
+    const { owner, relPath } = resolveHref(String(href));
+    const lane = req.query.lane === 'saved' ? 'saved' : 'live';
+
+    let actor = req.actor;
+    if (req.query.token) {
+      const grant = await resolveSaveToken(String(req.query.token));
+      if (grant) actor = { ...actor, grants: { ...actor.grants, saveToken: grant } };
+    }
+    const node = nodes.resolve(owner, relPath);
+    // The saved lane carries whole documents, so it is gated like a read; the
+    // live lane carries pre-strip peer snapshots, so it needs write.
+    const action = lane === 'saved' ? 'read' : 'write';
+    if (!can(actor, action, node, gateCtx)) return jsonError(res, 'not-found', 'Not found');
+
+    liveSync.subscribe(owner, relPath, res, { lane });
+    return undefined;
+  }));
+
+  // ---- the reserved v2 device lane ---------------------------------------
+  for (const name of RESERVED_SYNC_PATHS) {
+    system.all(`/sync/${name}`, (req, res) => {
+      res.status(410).json({
+        msg: 'The device sync lane is reserved for a future version.',
+        msgType: 'error',
+        code: 'reserved',
+      });
+    });
+  }
+}

package/src/routes/upload.js

@@ -0,0 +1,128 @@
+import path from 'upath';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { HostError } from '../spec/codes.js';
+import { documentUrlHeader } from '../spec/wire.js';
+import { readMultipart } from '../util/multipart.js';
+import { wrap } from '../util/express.js';
+import { assetsDirFor } from '../nodes/names.js';
+
+// spec §9 uploads.
+//
+// The document's lane, and it is not the dashboard's. The dashboard puts a file
+// wherever a person is looking, keeps the name they chose, and takes the scripts
+// and stylesheets a site loads. A document uploading is a different act with
+// different rules: the host picks the name so nothing is ever replaced, the file
+// lands in one predictable place beside the document, and anything that would
+// RUN on this origin is refused, because a document must not be able to install
+// code on its host by calling it an upload.
+//
+// Keeping those as two addresses rather than one address with two modes is
+// deliberate. Fold them together and the strict rules become a thing the caller
+// opts into by shaping the request, when they should be a property of the door.
+const UPLOAD_REFUSED = /\.(html?|xhtml|htmlclay|js|mjs|cjs|xml|xht|xsl|xslt)$/i;
+
+export function mountUploadRoutes({
+  system, config, ops, tenants, gateCtx, resolveTarget, resolveSaveToken,
+}) {
+  async function handleUpload(req, res, grant = null) {
+    if (config.capabilities.upload === false || config.features?.uploads === false) {
+      return jsonError(res, 'not-found', 'Not found');
+    }
+
+    let node = null;
+    let actor = req.actor;
+    if (grant) {
+      node = grant.node;
+      actor = { ...req.actor, grants: { ...req.actor.grants, saveToken: grant } };
+    } else {
+      const href = documentUrlHeader(req);
+      if (!href) return jsonError(res, 'bad-request', 'Document-URL header required.');
+      const found = await resolveTarget(req.actor, href, 'read');
+      if (!found) return jsonError(res, 'not-found', 'Not found');
+      node = found.node;
+    }
+
+    // Uploading is writing to the document by another route, so the document's
+    // own write permission is what decides it. A save token grants exactly that,
+    // which is what makes a sandboxed document able to upload at all.
+    if (!can(actor, 'write', node, gateCtx)) {
+      return jsonError(res, 'forbidden', 'You cannot upload to this document.');
+    }
+
+    const limit = config.limits.uploadBytes;
+    const contentType = String(req.headers['content-type'] || '');
+    if (!contentType.startsWith('multipart/form-data')) {
+      return jsonError(res, 'bad-request', 'Send the file as multipart/form-data.');
+    }
+
+    let files;
+    try {
+      ({ files } = await readMultipart(req, { limit, files: 20 }));
+    } catch (error) {
+      if (error instanceof HostError) return jsonError(res, error.code, error.message);
+      throw error;
+    }
+    if (!files.length) return jsonError(res, 'bad-request', 'No files in this upload.');
+
+    const dir = assetsDirFor(node.path);
+
+    // The whole batch is judged before any of it is stored. Refusing inside the
+    // write loop answers "that file cannot be uploaded" with the files before it
+    // already on disk, so the caller is told the upload failed and is given no
+    // way to learn what landed.
+    for (const file of files) {
+      const name = path.basename(String(file.filename || ''));
+      if (UPLOAD_REFUSED.test(name)) {
+        return jsonError(
+          res, 'unsupported-type',
+          'That kind of file runs when it is opened, so it cannot be uploaded. A document goes through the save lane.',
+        );
+      }
+      if (file.content.length > limit) {
+        return jsonError(res, 'too-large', `Files are limited to ${limit} bytes.`);
+      }
+    }
+
+    // Uploading is writing to the document by another route, and the quota is
+    // part of writing. Charged before the bytes land, for the reason the save
+    // lane states: a quota that only notices afterwards is an audit log, not a
+    // limit. Without this a tenant's document holds an upload token and can
+    // spend the owner's disk without limit.
+    if (node.owner && tenants.enabled) {
+      const bytes = files.reduce((total, file) => total + file.content.length, 0);
+      tenants.checkQuota(node.owner, { relPath: dir, bytes });
+    }
+
+    const uploads = [];
+    for (const file of files) {
+      const name = path.basename(String(file.filename || ''));
+      const stored = await ops.putUpload({ owner: node.owner, dir, name, content: file.content });
+      // Relative to the document's own URL, which §9 says is what the client
+      // resolves against. That is the one form correct in every realm, at any
+      // folder depth, and behind a proxy that mounts the host under a subpath;
+      // an absolute path would have to rebuild the realm prefix and would be
+      // wrong in all three cases.
+      // Percent-encoded, because what goes back is a URL and the stored name is a
+      // filename: this host deliberately keeps spaces in names, and a raw space
+      // makes the reference invalid. It survives in an `img src` because the
+      // browser repairs it, and breaks outright in `srcset`, where a space is the
+      // separator, and in an unquoted CSS `url()`. `name` stays the real filename
+      // so a person can find it in the file manager.
+      uploads.push({
+        name: stored.name,
+        url: `${encodeURIComponent(path.basename(dir))}/${encodeURIComponent(stored.name)}`,
+        bytes: stored.bytes,
+      });
+    }
+    return res.json({ msg: 'Uploaded', uploads });
+  }
+
+  system.post('/upload', wrap((req, res) => handleUpload(req, res)));
+
+  system.post('/upload/:token', wrap(async (req, res) => {
+    const grant = await resolveSaveToken(req.params.token);
+    if (!grant) return jsonError(res, 'unauthorized', 'This save token is not valid.');
+    return handleUpload(req, res, grant);
+  }));
+}

package/src/share/index.js

@@ -0,0 +1,207 @@
+import crypto from 'node:crypto';
+import express from 'express';
+import path from 'upath';
+import qrcode from 'qrcode-generator';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { HostError } from '../spec/codes.js';
+import { token as mintToken } from '../util/id.js';
+
+// Share links (§13).
+//
+// Many links per node, each labelled ("for Ben"), each view or edit, each
+// separately revocable, each optionally expiring. Tokens are hashed at rest and
+// the raw value is shown exactly once.
+//
+// A share grants a CAPABILITY SET for one node. It never promotes an identity.
+// That is the whole difference from the platform's no_auth -> app_user
+// elevation, which set isOwner unconditionally and turned a link to one page
+// into an account on the box.
+//
+// The cookie is keyed by NODE ID rather than by name, so renaming a shared
+// document does not break a link someone is already holding.
+
+const COOKIE_PREFIX = 'mk_share_';
+const COOKIE_MAX_AGE = 365 * 24 * 60 * 60;
+
+function hashShareToken(raw) {
+  return crypto.createHash('sha256').update(String(raw)).digest('hex');
+}
+
+function shareCookieName(nodeId) {
+  return `${COOKIE_PREFIX}${nodeId}`;
+}
+
+export function createShares({ store, nodes, clock, ids = { token: mintToken }, events}) {
+  function live(share) {
+    if (!share) return null;
+    if (share.revokedAt) return null;
+    if (share.expiresAt && share.expiresAt <= clock.now()) return null;
+    return share;
+  }
+
+  function resolveToken(raw) {
+    if (!store || !raw) return null;
+    return live(store.getShare(hashShareToken(raw)));
+  }
+
+  async function mint({ actor, owner = '', relPath, grantKind = 'view', label = null, expiresInDays = null, ctx = {} }) {
+    if (!store) throw new HostError('not-found', 'This host keeps no share links.');
+    if (grantKind !== 'view' && grantKind !== 'edit') {
+      throw new HostError('bad-request', 'A share is either view or edit.');
+    }
+    const node = nodes.materialize(nodes.resolve(owner, relPath));
+    if (!can(actor, 'admin', node, ctx)) throw new HostError('forbidden', 'Only the owner can share.');
+
+    const raw = ids.token(24);
+    const tokenHash = hashShareToken(raw);
+    const expiresAt = expiresInDays ? clock.now() + Number(expiresInDays) * 86_400_000 : null;
+    store.insertShare({
+      tokenHash, nodeId: node.id, grantKind, label: label ? String(label).slice(0, 120) : null,
+      createdAt: clock.now(), expiresAt,
+    });
+
+    events.emit('node-updated', { node, flag: 'share' });
+    // The raw token is returned here and never again: the table has only its hash.
+    return { token: raw, tokenHash, nodeId: node.id, grantKind, label, expiresAt };
+  }
+
+  async function revoke({ actor, tokenHash, ctx = {} }) {
+    if (!store) throw new HostError('not-found', 'This host keeps no share links.');
+    const share = store.getShare(tokenHash);
+    if (!share) throw new HostError('not-found', 'No such share link.');
+    const node = store.getNodeById(share.nodeId);
+    if (!can(actor, 'admin', node, ctx)) throw new HostError('forbidden', 'Only the owner can revoke.');
+
+    store.revokeShare(tokenHash, clock.now());
+    // Kill the save tokens minted through this link too, or the holder keeps
+    // writing for up to twelve hours after being cut off.
+    store.deleteSaveTokensForNode(share.nodeId);
+    events.emit('share-revoked', { nodeId: share.nodeId, tokenHash });
+    return true;
+  }
+
+  function list(nodeId) {
+    if (!store) return [];
+    return store.listShares(nodeId).map((share) => ({
+      tokenHash: share.tokenHash,
+      grantKind: share.grantKind,
+      label: share.label,
+      createdAt: share.createdAt,
+      expiresAt: share.expiresAt,
+      revokedAt: share.revokedAt,
+      lastUsedAt: share.lastUsedAt,
+      active: !!live(share),
+    }));
+  }
+
+  // Every share the caller can prove they hold, whether it applies to this
+  // request or not; can() picks the one that matches the node.
+  function grantsFor(req, res) {
+    if (!store) return [];
+    const found = [];
+    const seen = new Set();
+
+    const add = (share, raw) => {
+      if (!share || seen.has(share.tokenHash)) return;
+      seen.add(share.tokenHash);
+      found.push(share);
+      store.touchShare(share.tokenHash, clock.now());
+      if (raw && res && !req.cookies?.[shareCookieName(share.nodeId)]) {
+        res.cookie(shareCookieName(share.nodeId), raw, {
+          httpOnly: true, sameSite: 'lax', path: '/', maxAge: COOKIE_MAX_AGE,
+        });
+      }
+    };
+
+    const fromQuery = typeof req.query?.token === 'string' ? req.query.token : null;
+    if (fromQuery) add(resolveToken(fromQuery), fromQuery);
+
+    for (const [name, value] of Object.entries(req.cookies || {})) {
+      if (!name.startsWith(COOKIE_PREFIX)) continue;
+      const share = resolveToken(value);
+      if (share) add(share, null);
+      // A revoked or expired cookie is cleared so a stale one does not sit in
+      // the browser forever quietly failing.
+      else if (res) res.clearCookie(name, { path: '/' });
+    }
+
+    return found;
+  }
+
+  function qrSvg(url) {
+    const qr = qrcode(0, 'M');
+    qr.addData(url);
+    qr.make();
+    return qr.createSvgTag({ cellSize: 6, margin: 2, scalable: true });
+  }
+
+  return { mint, revoke, list, resolveToken, grantsFor, qrSvg, hashShareToken, shareCookieName };
+}
+
+export function mountShareRoutes(ctx) {
+  const { router, shares, nodes, store, gateCtx, wrap, publicUrl } = ctx;
+  const json = express.json({ limit: '64kb' });
+
+  function requireOwner(req, res, next) {
+    if (!can(req.actor, 'admin', null, gateCtx)) return jsonError(res, 'not-found', 'Not found');
+    return next();
+  }
+
+  function absolute(req, relPath, token) {
+    const base = publicUrl || `${req.protocol}://${req.get('host')}`;
+    const encoded = String(relPath).split('/').map(encodeURIComponent).join('/');
+    return `${base.replace(/\/$/, '')}/${encoded}?token=${encodeURIComponent(token)}`;
+  }
+
+  router.get('/share', requireOwner, wrap(async (req, res) => {
+    const relPath = String(req.query.path || '').replace(/^\/+/, '');
+    if (!relPath) return jsonError(res, 'bad-request', 'path is required.');
+    const node = nodes.get('', relPath);
+    return res.json({ ok: true, path: relPath, shares: node ? shares.list(node.id) : [] });
+  }));
+
+  router.post('/share', requireOwner, json, wrap(async (req, res) => {
+    const relPath = String(req.body?.path || '').replace(/^\/+/, '');
+    if (!relPath) return jsonError(res, 'bad-request', 'path is required.');
+    const minted = await shares.mint({
+      actor: req.actor,
+      relPath,
+      grantKind: req.body?.grant === 'edit' ? 'edit' : 'view',
+      label: req.body?.label ?? null,
+      expiresInDays: req.body?.expiresInDays ?? null,
+      ctx: gateCtx,
+    });
+    return res.json({
+      ok: true,
+      ...minted,
+      url: absolute(req, relPath, minted.token),
+      qrUrl: `/_/share/${encodeURIComponent(minted.token)}/qr`,
+    });
+  }));
+
+  router.post('/share/revoke', requireOwner, json, wrap(async (req, res) => {
+    const tokenHash = req.body?.tokenHash
+      || (req.body?.token ? shares.hashShareToken(req.body.token) : null);
+    if (!tokenHash) return jsonError(res, 'bad-request', 'tokenHash is required.');
+    await shares.revoke({ actor: req.actor, tokenHash, ctx: gateCtx });
+    return res.json({ ok: true });
+  }));
+
+  // The QR page is for handing a link to someone standing next to you, so it is
+  // owner-only: it prints the raw token, which is the credential itself.
+  router.get('/share/:token/qr', requireOwner, wrap(async (req, res) => {
+    const share = shares.resolveToken(req.params.token);
+    if (!share) return jsonError(res, 'not-found', 'No such share link.');
+    const node = store?.getNodeById(share.nodeId);
+    if (!node) return jsonError(res, 'not-found', 'No such share link.');
+    const url = absolute(req, node.path, req.params.token);
+    return ctx.ui.send(res, 'share-qr', {
+      title: `Share ${path.basename(node.path)}`,
+      name: path.basename(node.path),
+      grant: share.grantKind,
+      url,
+      qr: shares.qrSvg(url),
+    });
+  }));
+}