@nimbus-dev/connectors 0.4.0 → 0.5.0

package/connectors/apple/src/calendar-tools.ts

@@ -43,15 +43,59 @@ const listArgs = z.object({
   calendar: z.string().min(1).optional(),
 });
 
+/** A C0 control (CR, LF and TAB included), DEL, or a C1 control. */
+function isControlCode(code: number): boolean {
+  return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+}
+
+/**
+ * Whether `value` carries a control character anywhere. Event text reaches iCalendar content
+ * lines, where CR or LF ends a line and starts a new property; the SDK's escaping turns CRLF or LF
+ * into an escaped newline but leaves a bare CR. So the input is REFUSED here rather than relying
+ * on (or adding) an escape. Nothing is stripped.
+ */
+export function hasControlCharacter(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    if (isControlCode(value.charCodeAt(i))) return true;
+  }
+  return false;
+}
+
+/** Whether `value` carries any whitespace (Unicode `\s`) or control character. */
+export function hasWhitespaceOrControl(value: string): boolean {
+  return /\s/u.test(value) || hasControlCharacter(value);
+}
+
+export const ICLOUD_TEXT_REFUSAL = "must not contain a line break or other control character";
+export const ICLOUD_TIME_REFUSAL =
+  "must be a UTC time in the form YYYYMMDDTHHMMSSZ; all-day and floating times are not supported";
+export const ICLOUD_UID_REFUSAL =
+  "must be 1 to 200 characters, each a letter, a digit, '.', '_', '@' or '-'";
+export const ICLOUD_ATTENDEE_REFUSAL =
+  "each attendee must be one email address, with no whitespace or control character";
+
+/** `YYYYMMDDTHHMMSSZ`: a UTC date-time and nothing else (owner ruling OR-B4-6). */
+const UTC_DATE_TIME = /^\d{8}T\d{6}Z$/;
+const EVENT_UID = /^[A-Za-z0-9._@-]{1,200}$/;
+
+/** A free-text event field: refused, never cleaned, when it carries a control character. */
+function eventText(): z.ZodString {
+  return z.string().refine((s) => !hasControlCharacter(s), ICLOUD_TEXT_REFUSAL);
+}
+
 const createArgs = z.object({
-  calendar: z.string().min(1).optional(),
-  summary: z.string().min(1).max(1000),
-  start: z.string().min(1),
-  end: z.string().min(1),
-  description: z.string().max(10_000).optional(),
-  location: z.string().max(500).optional(),
-  attendees: z.array(z.email()).optional(),
-  uid: z.string().min(1).optional(),
+  calendar: eventText().min(1).optional(),
+  summary: eventText().min(1).max(1000),
+  start: z.string().regex(UTC_DATE_TIME, ICLOUD_TIME_REFUSAL),
+  end: z.string().regex(UTC_DATE_TIME, ICLOUD_TIME_REFUSAL),
+  description: eventText().max(10_000).optional(),
+  location: eventText().max(500).optional(),
+  // z.email() already refuses whitespace and controls today; the explicit check keeps that a
+  // stated property of THIS schema, not of zod's current email pattern.
+  attendees: z
+    .array(z.email().refine((s) => !hasWhitespaceOrControl(s), ICLOUD_ATTENDEE_REFUSAL))
+    .optional(),
+  uid: z.string().regex(EVENT_UID, ICLOUD_UID_REFUSAL).optional(),
 });
 
 const deleteArgs = z.object({
@@ -199,7 +243,7 @@ export function registerAppleCalendarTools(
       recoverable: true,
       scopeTargetOf: (p) => ({ kind: "calendar", value: p.calendar ?? "default" }),
     },
-    "Create a new event in iCloud Calendar via CalDAV PUT.",
+    "Create a new event in iCloud Calendar via CalDAV PUT. start and end are UTC, in the form YYYYMMDDTHHMMSSZ (all-day and floating times are refused). summary, description, location and calendar may not contain a line break or other control character; uid, when given, is 1-200 of A-Z a-z 0-9 . _ @ -.",
     createArgs,
     async (parsedData) => {
       const parsed = { success: true as const, data: parsedData };

package/connectors/confluence/src/tools.ts

@@ -71,6 +71,37 @@ function readPageSnapshot(res: { ok: boolean; status: number; text: string }): P
   };
 }
 
+/** One entry of `confluence_page_get`'s `ancestors`: what a caller needs, not the whole page. */
+export interface PageAncestor {
+  readonly id: string | null;
+  readonly title: string | null;
+}
+
+/**
+ * Narrow the `ancestors` Confluence expands on a page to `{ id, title }` per entry, in Confluence's
+ * order (the space's top-level page first, the page's direct parent last). An ancestor is a whole
+ * content object (links, extensions, status); a caller deciding where a page sits needs only its
+ * id, and the title is free. An entry without a string id keeps its place with `id: null` rather
+ * than being dropped, so the chain is never shorter than Confluence said. A reply with no
+ * `ancestors` array is returned as it came: absent stays absent, never an invented `[]`.
+ */
+export function withAncestorSummaries(page: unknown): unknown {
+  if (page === null || typeof page !== "object" || Array.isArray(page)) return page;
+  const obj = page as Record<string, unknown>;
+  const ancestors = obj["ancestors"];
+  if (!Array.isArray(ancestors)) return page;
+  const summaries: PageAncestor[] = ancestors.map((a: unknown) => {
+    const entry = a !== null && typeof a === "object" ? (a as Record<string, unknown>) : {};
+    const id = entry["id"];
+    const title = entry["title"];
+    return {
+      id: typeof id === "string" ? id : null,
+      title: typeof title === "string" ? title : null,
+    };
+  });
+  return { ...obj, ancestors: summaries };
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const CONFLUENCE_TOOL_NAMES = [
   "confluence_space_list",
@@ -150,14 +181,23 @@ export function registerConfluenceTools(
 
   reg(
     "confluence_page_get",
-    "Get a Confluence page with body.storage (GET /content/{id}).",
+    "Get a Confluence page with body.storage (GET /content/{id}). ancestors lists the pages above it as { id, title }, the top-level page first and the direct parent last.",
     confluencePageIdSchema,
     async (parsed) => {
       const id = encodeURIComponent(parsed.pageId);
       const res = await confFetch(
-        `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
+        `/content/${id}?expand=body.storage,version,history.lastUpdated,space,ancestors`,
       );
-      return mcpJsonResultFromTextIfOk("Confluence", res);
+      if (!res.ok) {
+        throw new Error(`Confluence ${String(res.status)}: ${res.text.slice(0, 400)}`);
+      }
+      let page: unknown;
+      try {
+        page = JSON.parse(res.text) as unknown;
+      } catch {
+        throw new Error("Confluence: invalid JSON response");
+      }
+      return mcpJsonResult(withAncestorSummaries(page));
     },
   );
 

package/connectors/obsidian/nimbus.extension.json

@@ -2,7 +2,7 @@
   "id": "com.nimbus.obsidian",
   "displayName": "Obsidian",
   "version": "0.1.0",
-  "description": "Local Obsidian vault connector (notes, backlinks). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem at spawn time by the Gateway. obsidian_append_to_daily_note requires HITL.",
+  "description": "Local Obsidian vault connector (notes, backlinks, daily notes). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem.read at spawn time by the Gateway, which may also add the vaults to permissions.filesystem.write at spawn (only while the owner has approved obsidian_append_to_daily_note for the model). obsidian_append_to_daily_note requires HITL; obsidian_daily_note_get is a read.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",

package/connectors/obsidian/src/tools.ts

@@ -2,11 +2,13 @@ import { createHash } from "node:crypto";
 import {
   closeSync,
   fstatSync,
+  lstatSync,
   mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
   readSync,
+  realpathSync,
   statSync,
   writeSync,
 } from "node:fs";
@@ -54,6 +56,93 @@ function assertWithinVault(vaultRoot: string, relPath: string): string {
   return candidate;
 }
 
+/** Whether anything, a dangling link included, sits at `p`. */
+function pathEntryExists(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuse `abs` (a path `assertWithinVault` already accepted) when the place it really names is
+ * outside the vault: a folder or note that is, or passes through, a symlink or junction out of the
+ * vault. `assertWithinVault` compares strings, so it cannot see a link.
+ *
+ * The note, and the folders above it, may not exist yet (the append creates them), so the check
+ * resolves the deepest part of the path that does exist; whatever is created below it is created
+ * inside it. A dangling link cannot be resolved and is refused. The check and the later open are
+ * two system calls, so a link swapped in between them is not seen here: the gateway's sandbox,
+ * which grants only the vaults, is the boundary (stated bound).
+ */
+export function assertRealpathWithinVault(vaultRoot: string, abs: string, relPath: string): void {
+  const realRoot = realpathSync(resolve(vaultRoot));
+  const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  let probe = abs;
+  while (!pathEntryExists(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  let real: string;
+  try {
+    real = realpathSync(probe);
+  } catch {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+  if (real !== realRoot && !real.startsWith(prefix)) {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+}
+
+/** How much of the end of a daily note `obsidian_daily_note_get` returns. */
+export const DAILY_NOTE_TAIL_BYTES = 16 * 1024;
+
+/** The positioned-read signature of `readSync`, injectable so a test can count what is read. */
+export type PositionedRead = (
+  fd: number,
+  buffer: Buffer,
+  offset: number,
+  length: number,
+  position: number,
+) => number;
+
+/**
+ * The size of the file at `abs` and its last `maxBytes` bytes, decoded as UTF-8.
+ *
+ * Positioned reads of at most `maxBytes` in all, never the whole file. When the window starts
+ * inside the file, the UTF-8 continuation bytes it begins with (the rest of a character the window
+ * cut) are dropped, so the tail starts on a character boundary.
+ */
+export function readUtf8Tail(
+  abs: string,
+  maxBytes: number,
+  read: PositionedRead = readSync,
+): { size: number; tail: string } {
+  const fd = openSync(abs, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buf = Buffer.alloc(length);
+    let got = 0;
+    while (got < length) {
+      const n = read(fd, buf, got, length - got, start + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    let skip = 0;
+    if (start > 0) {
+      while (skip < 3 && skip < got && ((buf[skip] ?? 0) & 0xc0) === 0x80) skip++;
+    }
+    return { size, tail: buf.subarray(skip, got).toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 function loadVaultPaths(): readonly string[] {
   const raw = requireProcessEnv("OBSIDIAN_VAULT_PATHS_JSON");
   let parsed: unknown;
@@ -98,7 +187,10 @@ function walkForVaults(dir: string, out: VaultEntry[]): void {
     const sub = join(dir, e);
     let isDir = false;
     try {
-      const st = statSync(sub);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() was always false and
+      // discovery used to find a vault through a symlink or junction outside the configured root.
+      // Every link below a root is skipped, so a discovered vault is physically under its root.
+      const st = lstatSync(sub);
       isDir = st.isDirectory() && !st.isSymbolicLink();
     } catch {
       continue;
@@ -128,7 +220,9 @@ function walkNotes(currentDir: string, vaultRoot: string, out: string[]): void {
     let isFile = false;
     let isDir = false;
     try {
-      const st = statSync(full);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() is always false and the
+      // walk used to list notes through a symlink or junction, out of the vault included.
+      const st = lstatSync(full);
       if (st.isSymbolicLink()) continue;
       isFile = st.isFile();
       isDir = st.isDirectory();
@@ -151,6 +245,7 @@ function readNote(
   relPath: string,
 ): { title: string; body: string; raw: string } {
   const abs = assertWithinVault(vaultRoot, relPath);
+  assertRealpathWithinVault(vaultRoot, abs, relPath);
   const raw = readFileSync(abs, "utf8");
   const m = FRONTMATTER_RE.exec(raw);
   const body = m === null ? raw : raw.slice(m[0].length);
@@ -193,6 +288,7 @@ export const OBSIDIAN_TOOL_NAMES = [
   "obsidian_get",
   "obsidian_search",
   "obsidian_append_to_daily_note",
+  "obsidian_daily_note_get",
 ] as const;
 
 /** The date tokens an Obsidian daily-note filename format may contain. */
@@ -400,6 +496,28 @@ export function registerObsidianTools(
     }),
   );
 
+  /**
+   * The vault and the daily note a daily-note tool names: ONE resolution, shared by the append and
+   * the read, so the read shows exactly the note the append would write. String containment
+   * (`assertWithinVault`) and then realpath containment (`assertRealpathWithinVault`).
+   */
+  function resolveDailyNote(parsed: { vault_id: string; date_iso?: string | undefined }): {
+    v: VaultEntry;
+    rel: string;
+    abs: string;
+  } {
+    const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
+    if (v === undefined) {
+      throw new Error("Unknown vault_id");
+    }
+    const date =
+      parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
+    const rel = resolveDailyNoteRelativePath(v.root, date);
+    const abs = assertWithinVault(v.root, rel);
+    assertRealpathWithinVault(v.root, abs, rel);
+    return { v, rel, abs };
+  }
+
   const appendDailyNoteSchema = z.object({
     vault_id: z.string().min(1),
     content: z.string().min(1),
@@ -420,15 +538,10 @@ export function registerObsidianTools(
     "Append text to today's Obsidian daily note. Creates the file if it does not exist. Always appends — never overwrites. Adds a leading newline when the existing file does not end in one. Requires HITL `obsidian.note.append`.",
     appendDailyNoteSchema,
     syncToolHandler((parsed) => {
-      const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
-      if (v === undefined) {
-        throw new Error("Unknown vault_id");
-      }
-      const date =
-        parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
-      const rel = resolveDailyNoteRelativePath(v.root, date);
-      const abs = assertWithinVault(v.root, rel);
+      const { v, rel, abs } = resolveDailyNote(parsed);
       mkdirSync(dirname(abs), { recursive: true });
+      // Again, now the folders exist: what was created must still be inside the vault.
+      assertRealpathWithinVault(v.root, abs, rel);
 
       const fd = openSync(abs, "a+");
       let bytes = 0;
@@ -463,4 +576,39 @@ export function registerObsidianTools(
       });
     }),
   );
+
+  const dailyNoteGetSchema = z.object({
+    vault_id: z.string().min(1),
+    date_iso: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .optional(),
+  });
+
+  reg(
+    "obsidian_daily_note_get",
+    `Read the end of the Obsidian daily note that obsidian_append_to_daily_note would write for the same vault_id and date_iso (today in UTC when omitted). Returns { vault_id, vault_name, path, exists, size_bytes, tail }: tail is at most the last ${String(DAILY_NOTE_TAIL_BYTES)} bytes, starting on a character boundary; a missing note is exists: false, size_bytes: 0, tail "". Read-only.`,
+    dailyNoteGetSchema,
+    syncToolHandler((parsed) => {
+      const { v, rel, abs } = resolveDailyNote(parsed);
+      let exists = false;
+      let size = 0;
+      let tail = "";
+      if (pathEntryExists(abs)) {
+        if (!statSync(abs).isFile()) {
+          throw new Error(`Daily note is not a file: ${rel}`);
+        }
+        exists = true;
+        ({ size, tail } = readUtf8Tail(abs, DAILY_NOTE_TAIL_BYTES));
+      }
+      return jsonResult({
+        vault_id: v.id,
+        vault_name: v.name,
+        path: rel,
+        exists,
+        size_bytes: size,
+        tail,
+      });
+    }),
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },