@3sln/trove 0.0.2

package/packages/server/src/mcp/tools.js

@@ -0,0 +1,351 @@
+// What an agent can actually do with the drive.
+//
+// Every tool here goes through the SAME permission checks the HTTP API uses. That is the
+// whole security posture: an agent holding Alice's token is Alice, with Alice's
+// collections and Alice's write access, and there is no MCP-shaped bypass around the
+// collection ACL. The alternative — a service account the agent shares — would mean one
+// compromised agent reads everyone's drive.
+//
+// Descriptions are written for a MODEL to read. That means saying what a tool is FOR and
+// when to reach for it, not restating the parameter names it can already see in the
+// schema. The single most valuable sentence in this file is the one telling the model
+// that this drive has no folders, because every model assumes otherwise and will
+// otherwise spend its turns looking for a path that does not exist.
+
+import { TroveError } from '@3sln/trove/core';
+import { troveUri } from '@3sln/trove/core/links.js';
+import { toolText } from './protocol.js';
+
+// A file read has to fit in a context window and in memory. Past this the tool returns
+// the head and says so, which is far more useful than refusing or than silently
+// truncating and letting the model reason about half a document as if it were whole.
+const MAX_READ_BYTES = 256 * 1024;
+const MAX_RESULTS = 50;
+
+const INSTRUCTIONS = `Trove is a personal file drive with semantic search.
+
+There are NO FOLDERS and no paths. Files live in flat "collections" (the default one is
+called "default"), and are found by searching rather than by browsing a tree. If you are
+looking for something, search for it — do not try to construct a path.
+
+Files reference each other with trove: URIs (trove:default?name=notes.md). Search matches
+meaning as well as words, so a description of the content works as a query.`;
+
+/**
+ * Whether this deployment has an ACL layer at all — from configuration, never from
+ * whether `ctx.collections` happens to be there. The two agree while everything is
+ * wired correctly and diverge exactly when it is not, and here the failure mode is an
+ * agent quietly reading every collection in the drive.
+ */
+const enforcing = (ctx) => ctx.config?.collections !== false;
+
+/**
+ * Collections this principal can read, or undefined when there is no ACL layer.
+ *
+ * `undefined` means "do not scope the query", which is only correct when there is
+ * nothing to scope BY. Search and backlinks reach across collections by design, so an
+ * unscoped query hands back names, ids and `trove:` URIs from collections the caller
+ * cannot read.
+ */
+async function readable(ctx, narrowTo) {
+  if (!enforcing(ctx)) return undefined;
+  const ids = (await ctx.collections.list(ctx.principal)).map((c) => c.id);
+  return narrowTo ? ids.filter((id) => id === narrowTo) : ids;
+}
+
+/**
+ * A file, and the operations this agent may perform on it.
+ *
+ * `access.node` resolves by id, by name within a collection, or by `trove:` URI, and
+ * throws when the capability is not held — so a tool that gets a handle back is a tool
+ * that may act. Missing becomes the sentence a MODEL should read: "Item" tells it
+ * nothing, and it will retry the same call.
+ */
+async function fileHandle(ctx, file, collectionId, capability) {
+  try {
+    return await ctx.access.node(file, capability, { collectionId });
+  } catch (err) {
+    if (err?.code === 'not_found') throw TroveError.notFound(`No file called "${file}"`);
+    throw err;
+  }
+}
+
+/** Everything about a node worth telling a model, and nothing internal. */
+function describeNode(node) {
+  return {
+    id: node.id,
+    name: node.name,
+    uri: troveUri(node),
+    collection: node.collectionId,
+    contentType: node.contentType,
+    size: node.size,
+    updatedAt: node.updatedAt,
+    ...(node.tags && Object.keys(node.tags).length ? { tags: node.tags } : {}),
+  };
+}
+
+const textLike = (type) => !type || /^text\/|json|xml|yaml|javascript|csv|markdown|x-sh/.test(type);
+
+async function readText(handle) {
+  const { stream } = await handle.read({ range: { start: 0, end: MAX_READ_BYTES } });
+  const text = await new Response(stream).text();
+  return { text, truncated: handle.size > MAX_READ_BYTES };
+}
+
+/**
+ * Register Trove's tools on an McpServer.
+ *
+ * `ctx` at call time carries { vfs, collections, principal } — the same objects the HTTP
+ * routes get, so the two surfaces cannot drift apart on what a given user may do.
+ */
+export function registerTroveTools(server) {
+  server.instructions = INSTRUCTIONS;
+
+  server.tool({
+    name: 'search_files',
+    title: 'Search the drive',
+    readOnly: true,
+    description:
+      'Search the drive by meaning and by keyword. This is the primary way to find anything — '
+      + 'there are no folders to browse. A natural description of the content works ("notes about '
+      + 'the boat refit"); so does an exact phrase. Append #tag to require a tag, or #key:value to '
+      + 'compare one (=, !=, <, <=, >, >=). Returns matching files with a snippet where there is one.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'What to look for, in words.' },
+        collection: { type: 'string', description: 'Restrict to one collection. Omit to search everything you can read.' },
+        limit: { type: 'integer', description: `Maximum results (default 10, max ${MAX_RESULTS}).` },
+      },
+      required: ['query'],
+    },
+    async run({ query, collection, limit }, ctx) {
+      if (!query?.trim()) throw TroveError.invalid('query is required');
+      const collectionIds = await readable(ctx, collection);
+      const { results, resolved } = await ctx.vfs.query(query, {
+        limit: Math.min(Math.max(1, limit || 10), MAX_RESULTS),
+        collectionIds,
+      });
+      const items = results.map((r) => ({
+        ...describeNode(r.node),
+        score: r.score,
+        ...(r.snippet ? { snippet: r.snippet } : {}),
+      }));
+      if (!items.length) {
+        // Saying "nothing matched" beats an empty array: a model reading `[]` often
+        // retries the identical query, while a sentence prompts it to rephrase.
+        return toolText(`No files matched "${query}". Try different words — search matches meaning, so a description of the content works.`,
+          { structured: { results: [] } });
+      }
+      return toolText(JSON.stringify({ resolved, results: items }, null, 2), { structured: { results: items } });
+    },
+  });
+
+  server.tool({
+    name: 'list_files',
+    title: 'List a collection',
+    readOnly: true,
+    description:
+      'List what is in a collection, most recently changed first. Use this to see what exists; use '
+      + 'search_files to find something specific. Large collections are paged — pass the returned '
+      + 'cursor to continue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        collection: { type: 'string', description: 'Which collection (default: "default").' },
+        cursor: { type: 'string', description: 'Continue from a previous call.' },
+        limit: { type: 'integer', description: `Maximum items (default 25, max ${MAX_RESULTS}).` },
+      },
+    },
+    async run({ collection = 'default', cursor, limit }, ctx) {
+      // The description promises recency and `list` defaults to alphabetical, so it
+      // has to be asked for. An agent answering "what did I add recently?" off the top
+      // of an alphabetical list is confidently wrong in a way nothing surfaces.
+      const page = await (await ctx.access.collection(collection, 'read')).list({
+        cursor, sort: 'updatedAt', order: 'desc',
+        limit: Math.min(Math.max(1, limit || 25), MAX_RESULTS),
+      });
+      const items = (page.items || []).map(describeNode);
+      return toolText(JSON.stringify({
+        collection, items, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+      }, null, 2), { structured: { items, nextCursor: page.nextCursor || null } });
+    },
+  });
+
+  server.tool({
+    name: 'read_file',
+    title: 'Read a file',
+    readOnly: true,
+    description:
+      'Read a file\'s text. Identify it by id, by name, or by a trove: URI — whichever you have. '
+      + 'Binary files (images, video, archives) are not returned as text; their details are '
+      + 'returned instead so you know what is there.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'A file id, a name, or a trove: URI.' },
+        collection: { type: 'string', description: 'Which collection to look in when given a name (default: "default").' },
+      },
+      required: ['file'],
+    },
+    async run({ file, collection = 'default' }, ctx) {
+      const handle = await fileHandle(ctx, file, collection, 'read');
+      const node = handle.node;
+      if (!textLike(node.contentType)) {
+        return toolText(`"${node.name}" is ${node.contentType || 'binary'} (${node.size} bytes) and has no text to read.\n`
+          + JSON.stringify(describeNode(node), null, 2), { structured: describeNode(node) });
+      }
+      const { text, truncated } = await readText(handle);
+      // Saying it was cut off matters: a model that believes it read a whole document
+      // will confidently answer questions about the part it never saw.
+      return toolText(truncated
+        ? `${text}\n\n[truncated — showing the first ${MAX_READ_BYTES} bytes of ${node.size}]`
+        : text);
+    },
+  });
+
+  server.tool({
+    name: 'write_file',
+    title: 'Write a file',
+    description:
+      'Create a file, or replace one that already has this name. Requires write access to the '
+      + 'collection. Link to other files with trove: URIs (trove:default?name=other.md) — that is '
+      + 'how things are related here, since there are no folders.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'The file name, including its extension.' },
+        content: { type: 'string', description: 'The text to write.' },
+        collection: { type: 'string', description: 'Which collection (default: "default").' },
+        contentType: { type: 'string', description: 'Override the type guessed from the name.' },
+      },
+      required: ['name', 'content'],
+    },
+    async run({ name, content, collection = 'default', contentType }, ctx) {
+      if (!name?.trim()) throw TroveError.invalid('name is required');
+      const into = await ctx.access.collection(collection, 'write');
+      // No contentType falls through to the vfs's own guess from the name.
+      const node = await into.writeFile(name, content ?? '', { contentType });
+      return toolText(`Wrote ${node.name} (${node.size} bytes) — ${troveUri(node)}`,
+        { structured: describeNode(node) });
+    },
+  });
+
+  server.tool({
+    name: 'delete_file',
+    title: 'Move a file to the trash',
+    description:
+      'Move a file to the trash. It leaves the drive but is kept and can be restored, so this is '
+      + 'recoverable — it does not destroy anything. Requires delete access to the collection.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'A file id, a name, or a trove: URI.' },
+        collection: { type: 'string', description: 'Which collection to look in when given a name.' },
+      },
+      required: ['file'],
+    },
+    async run({ file, collection = 'default' }, ctx) {
+      const handle = await fileHandle(ctx, file, collection, 'delete');
+      await handle.remove();
+      return toolText(`Moved "${handle.name}" to the trash. It can be restored from the drive's trash.`);
+    },
+  });
+
+  server.tool({
+    name: 'list_collections',
+    title: 'List collections',
+    readOnly: true,
+    description:
+      'List the collections you can see and what you may do in each. Collections are the top-level '
+      + 'division of the drive — the closest thing here to a folder, except they do not nest.',
+    inputSchema: { type: 'object', properties: {} },
+    async run(_args, ctx) {
+      if (!enforcing(ctx)) {
+        return toolText(JSON.stringify({ collections: [{ id: 'default', capabilities: ['read', 'write', 'delete'] }] }, null, 2));
+      }
+      const list = await ctx.collections.list(ctx.principal);
+      return toolText(JSON.stringify({ collections: list }, null, 2), { structured: { collections: list } });
+    },
+  });
+
+  server.tool({
+    name: 'get_file_info',
+    title: 'Get a file\'s details',
+    readOnly: true,
+    description:
+      'Everything known about one file — type, size, when it changed, its tags, and which other '
+      + 'files link to it. Use the backlinks to follow how things are connected.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'A file id, a name, or a trove: URI.' },
+        collection: { type: 'string', description: 'Which collection to look in when given a name.' },
+      },
+      required: ['file'],
+    },
+    async run({ file, collection = 'default' }, ctx) {
+      const handle = await fileHandle(ctx, file, collection, 'read');
+      const node = handle.node;
+      // Scoped, exactly like the HTTP route. Backlinks reach ACROSS collections by
+      // design — that is what makes them useful — so an unscoped query hands back the
+      // names, ids and trove: URIs of files inside collections the caller cannot read.
+      const collectionIds = await readable(ctx);
+      const backlinks = await handle.backlinks({ limit: 20, collectionIds })
+        // Distinguishable from "nothing links here", which in a drive with no folders is
+        // a load-bearing fact an agent will reason from.
+        .catch((err) => { throw TroveError.transient(`Could not read backlinks: ${err.message}`); });
+      const info = {
+        ...describeNode(node),
+        backlinks: (backlinks || []).map((n) => ({ id: n.id, name: n.name, uri: troveUri(n) })),
+      };
+      return toolText(JSON.stringify(info, null, 2), { structured: info });
+    },
+  });
+
+  // Resources, so a client that prefers attaching context to a conversation over calling
+  // a tool has the same reach. The URIs are Trove's own `trove:` scheme rather than
+  // something invented for MCP — one name for a file across the whole system.
+  server.resources({
+    async list(params, ctx) {
+      const ids = await readable(ctx);
+      const out = [];
+      for (const cid of ids || ['default']) {
+        const page = await (await ctx.access.collection(cid, 'read')).list({ limit: 100 });
+        for (const node of page.items || []) {
+          out.push({
+            uri: troveUri(node),
+            name: node.name,
+            mimeType: node.contentType || 'application/octet-stream',
+            ...(node.size != null ? { size: node.size } : {}),
+          });
+        }
+      }
+      return { resources: out };
+    },
+    async read(params, ctx) {
+      let handle;
+      try {
+        handle = await ctx.access.node(params.uri, 'read');
+      } catch (err) {
+        if (err?.code === 'not_found') throw TroveError.notFound(`No such resource: ${params.uri}`);
+        throw err;
+      }
+      const node = handle.node;
+      if (!textLike(node.contentType)) {
+        // Base64 rather than refusing: a client that asked for an image wants the image.
+        const { stream } = await handle.read({ range: { start: 0, end: MAX_READ_BYTES } });
+        const bytes = new Uint8Array(await new Response(stream).arrayBuffer());
+        let bin = '';
+        for (const b of bytes) bin += String.fromCharCode(b);
+        return { contents: [{ uri: params.uri, mimeType: node.contentType, blob: btoa(bin) }] };
+      }
+      const { text } = await readText(handle);
+      return { contents: [{ uri: params.uri, mimeType: node.contentType || 'text/plain', text }] };
+    },
+  });
+
+  return server;
+}
+
+export { MAX_READ_BYTES, INSTRUCTIONS };

package/packages/server/src/router.js

@@ -0,0 +1,229 @@
+// A tiny Web-standard router: register (method, pattern) → handler, match an
+// incoming Request, and produce a Response. Patterns use ':param' segments
+// (e.g. '/uploads/:id/parts/:n'). Handlers receive { req, params, query, url }
+// and return a Response (or a plain object → JSON). All errors funnel through
+// one place so a TroveError becomes the right status + JSON body, and anything
+// unexpected becomes a clean 500 without leaking internals.
+
+import { TroveError, wrapError, ErrorCode, publicOrigin } from '@3sln/trove/core';
+import { leaseScope } from './scope.js';
+
+// Methods that change state. A GET is safe by definition, so it isn't checked.
+const UNSAFE_METHODS = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
+
+/**
+ * Refuse a state-changing request that another site made using the user's session.
+ *
+ * The CORS allowlist governs whether an attacker can READ the reply, and it only stops
+ * requests that need a preflight. A POST with `content-type: text/plain` is a CORS
+ * *simple request*: no preflight is sent, the allowlist is never consulted, and the
+ * write happens. The reply being unreadable is no comfort when the call was
+ * `delete_file`. Both the JSON API and the MCP endpoint were reachable that way, and
+ * the zero-config deployment needs no credential at all — the attacker's own browser
+ * is the credential.
+ *
+ * Browsers send `Sec-Fetch-Site` on every request and `Origin` on every state-changing
+ * one, so a cross-site call identifies itself. Non-browser clients (curl, an agent, a
+ * script) send neither and are unaffected — they carry no ambient credential, which is
+ * the entire basis of the attack. A bearer token is likewise not ambient, but it is not
+ * special-cased: a request that presents one is same-origin or scripted anyway.
+ *
+ * @returns {Response|null} a 403 to return instead of handling, or null to proceed
+ */
+export function crossSiteRefusal(req, config = {}) {
+  if (!UNSAFE_METHODS.has(req.method)) return null;
+  const site = req.headers.get('sec-fetch-site');
+  const origin = req.headers.get('origin');
+  if (!site && !origin) return null; // not a browser
+
+  // An operator who opted into CORS for an origin meant it: that site may call us.
+  const allowed = corsOriginFor(config?.corsOrigin, origin);
+  if (allowed === '*' || (allowed && allowed === origin)) return null;
+
+  if (site) {
+    if (site === 'same-origin' || site === 'none') return null;
+  } else if (origin === publicOrigin(req, config) || origin === new URL(req.url).origin) {
+    return null;
+  }
+  return json({
+    error: {
+      code: 'forbidden',
+      message: 'Cross-site requests may not change this drive. If this is intentional, set TROVE_CORS_ORIGIN.',
+      retryable: false,
+    },
+  }, 403);
+}
+
+export class Router {
+  constructor() {
+    this.routes = [];
+  }
+
+  /**
+   * @param {string} method
+   * @param {string} pattern
+   * @param {string[]|Function} depsOrHandler  the resources this route needs, by
+   *   name — or the handler, for a route that needs none.
+   * @param {Function} [maybeHandler]
+   *
+   * Declaring dependencies is the point. Every handler used to receive one
+   * object carrying the whole server: vfs, collections, kv, sqlite, plugins,
+   * tasks, issues, sidecar, notifications, identity, mcp. That is a service
+   * locator — nothing recorded what a route used, so nothing stopped it reaching
+   * for more, and "what does this endpoint touch" could only be answered by
+   * reading it. Named here, the answer is in the route table, and a route that
+   * did not ask for `plugins` does not get `plugins`.
+   */
+  add(method, pattern, depsOrHandler, maybeHandler) {
+    const handler = maybeHandler ?? depsOrHandler;
+    const deps = maybeHandler ? depsOrHandler : [];
+    const segs = pattern.split('/').filter(Boolean);
+    this.routes.push({ method, segs, handler, deps });
+    return this;
+  }
+  get(p, d, h) { return this.add('GET', p, d, h); }
+  post(p, d, h) { return this.add('POST', p, d, h); }
+  put(p, d, h) { return this.add('PUT', p, d, h); }
+  delete(p, d, h) { return this.add('DELETE', p, d, h); }
+
+  #match(method, pathname) {
+    const parts = pathname.split('/').filter(Boolean);
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      if (route.segs.length !== parts.length) continue;
+      const params = {};
+      let ok = true;
+      for (let i = 0; i < route.segs.length; i++) {
+        const s = route.segs[i];
+        // A malformed percent-escape (`/api/uploads/%ZZ/status`) makes
+        // decodeURIComponent throw a URIError — and #match runs OUTSIDE the try below,
+        // so it escaped the error funnel entirely and rejected the whole handle() call.
+        // A bad escape names nothing, which is a 404, not a 500.
+        if (s.startsWith(':')) {
+          try {
+            params[s.slice(1)] = decodeURIComponent(parts[i]);
+          } catch {
+            ok = false;
+            break;
+          }
+        }
+        else if (s !== parts[i]) { ok = false; break; }
+      }
+      if (ok) return { route, params };
+    }
+    return null;
+  }
+
+  /**
+   * @param {Request} req
+   * @param {object} [ctx] extra context merged into the handler arg (e.g. { vfs })
+   */
+  async handle(req, ctx = {}) {
+    const url = new URL(req.url);
+    // Cross-origin sharing is OFF by default (the app is same-origin); an operator
+    // opts in with TROVE_CORS_ORIGIN ('*' or a specific origin) → config.corsOrigin.
+    const origin = corsOriginFor(ctx.config?.corsOrigin, req.headers.get('origin'));
+    if (req.method === 'OPTIONS') return cors(new Response(null, { status: 204 }), origin);
+
+    const refused = crossSiteRefusal(req, ctx.config);
+    if (refused) return cors(refused, origin);
+
+    const found = this.#match(req.method, url.pathname);
+    if (!found) return cors(json({ error: { code: 'not_found', message: 'No such route' } }, 404), origin);
+
+    const query = Object.fromEntries(url.searchParams);
+    // Exactly what the route declared, leased for exactly the request. Released
+    // in `finally`, so a handler that throws still gives its resources back.
+    let lease = null;
+    // Handles obtained during the request, released with it. `access` is how a
+    // handler asks for an AUTHORIZED view of a node, collection or upload: the
+    // grant is carried by the object it hands back, so there is no unrestricted
+    // service and no raw id left over to use with one.
+    const scope = leaseScope(ctx.container, ctx.principal);
+    const access = scope.access;
+    try {
+      lease = ctx.container ? await ctx.container.lease(found.route.deps) : null;
+      const result = await found.route.handler({
+        req, params: found.params, query, url, access, ...ctx, ...(lease?.resources || {}),
+      });
+      const res = result instanceof Response ? result : json(result ?? { ok: true });
+      return cors(res, origin);
+    } catch (raw) {
+      const err = raw instanceof TroveError ? raw : wrapError(raw);
+      if (err.code === ErrorCode.INTERNAL) console.error('Unhandled:', err.cause || err);
+      return cors(json(err.toJSON(), err.status), origin);
+    } finally {
+      await scope.release();
+      await lease?.release();
+    }
+  }
+}
+
+// Resolve the Access-Control-Allow-Origin value: null (no CORS) unless configured.
+// '*' echoes '*'; a configured origin is echoed only when the request matches it
+// (so credentials-mode requests get a specific origin, not a wildcard).
+function corsOriginFor(configured, reqOrigin) {
+  if (!configured) return null;
+  if (configured === '*') return '*';
+  const allowed = String(configured).split(',').map((s) => s.trim()).filter(Boolean);
+  return reqOrigin && allowed.includes(reqOrigin) ? reqOrigin : null;
+}
+
+export function json(body, status = 200, headers = {}) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
+  });
+}
+
+export function cors(res, origin = null) {
+  const out = writable(res);
+  // Never let a browser sniff an API response into a different content type.
+  out.headers.set('x-content-type-options', 'nosniff');
+  if (origin) {
+    out.headers.set('access-control-allow-origin', origin);
+    if (origin !== '*') out.headers.set('vary', 'Origin');
+    out.headers.set('access-control-allow-methods', 'GET,POST,PUT,DELETE,OPTIONS');
+    out.headers.set('access-control-allow-headers', 'content-type, authorization, x-trove-indexer');
+    out.headers.set('access-control-expose-headers', 'content-range, accept-ranges, etag, content-length, content-disposition');
+  }
+  return out;
+}
+
+// `Response.redirect()` produces a response whose headers guard is IMMUTABLE — setting
+// anything on it throws `TypeError: immutable`. Every response funnels through cors(),
+// so on a runtime that enforces the guard (Node, Workers; Bun happens not to) a single
+// presigned-download redirect became a 500 caught by the same try/catch that logs it as
+// an internal error. Copy into a plain Response, whose headers are always writable.
+function writable(res) {
+  try {
+    res.headers.set('x-content-type-options', 'nosniff');
+    return res;
+  } catch {
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers: new Headers(res.headers) });
+  }
+}
+
+/**
+ * Parse a Range header (single range only).
+ *
+ * `bytes=500-999` → `{start, end}`. `bytes=-500` is the SUFFIX form and means the last
+ * 500 bytes, not the first 501 — it resolves against the object's real size, so it comes
+ * back as `{suffix}` for the storage layer to apply.
+ *
+ * @returns {{start:number, end?:number}|{suffix:number}|null}
+ */
+export function parseRange(header) {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!m) return null;
+  if (m[1] === '') {
+    if (m[2] === '') return null; // "bytes=-" is neither form
+    const suffix = parseInt(m[2], 10);
+    return Number.isNaN(suffix) ? null : { suffix };
+  }
+  const start = parseInt(m[1], 10);
+  const end = m[2] === '' ? undefined : parseInt(m[2], 10);
+  if (Number.isNaN(start)) return null;
+  return { start, end };
+}