@lanes-sh/link 0.1.0

package/src/connectivity/transports/dav/request.ts

@@ -0,0 +1,161 @@
+import type { ToolResult } from '#connectivity';
+import { DAV, find, findAll, parseDav, successful, textOf, type DavNode } from './xml.ts';
+import type { DavConnectorOptions } from './index.ts';
+
+/**
+ * The HTTP half of DAV: one request helper, the redirect rule, and the
+ * connect-time credential check.
+ *
+ * Everything here is protocol plumbing that knows nothing about calendars or
+ * contacts, which is why it is separate from both.
+ */
+
+/**
+ * Check the credential against the server, returning the username it accepted.
+ *
+ * This is the one place the connector builds an Authorization header itself,
+ * because there is no `ConnectorContext` at connect time to do it — the
+ * connection does not exist in config yet. It never reads the credential
+ * *store*: what it gets is already resolved and bound to one account.
+ */
+export async function validate(
+  options: DavConnectorOptions,
+  doFetch: typeof globalThis.fetch,
+): Promise<string | null> {
+  if (!options.credential) return null;
+
+  const { username, password } = await options.credential();
+  const encoded = Buffer.from(`${username}:${password}`, 'utf8').toString('base64');
+  const wellKnown = new URL(
+    options.service === 'caldav' ? '/.well-known/caldav' : '/.well-known/carddav',
+    options.baseUrl,
+  ).href;
+
+  const reply = await davRequest(
+    doFetch,
+    async (request) => {
+      const authorised = new Request(request, { headers: new Headers(request.headers) });
+      authorised.headers.set('authorization', `Basic ${encoded}`);
+      return authorised;
+    },
+    wellKnown,
+    'PROPFIND',
+    PRINCIPAL_BODY,
+    { depth: '0' },
+  );
+
+  if (reply.status === 401 || reply.status === 403) {
+    throw new Error(
+      `The server rejected the credential for ${username}.` +
+        (options.troubleshooting ? `\n  ${options.troubleshooting}` : ''),
+    );
+  }
+  if (reply.status >= 400) {
+    throw new Error(`The server refused discovery (${reply.status}).`);
+  }
+
+  return username;
+}
+
+/**
+ * The `href` inside a named property, from a propstat that actually succeeded.
+ *
+ * A multistatus reports status *per property*, so the presence of an element is
+ * not the presence of a value: iCloud answers `<current-user-principal/>`, empty,
+ * under a 404 propstat. Reading that as an answer is how discovery silently
+ * concludes you have no principal.
+ */
+export function hrefOfProperty(tree: DavNode, qname: string): string | undefined {
+  for (const response of findAll(tree, `{${DAV}}response`)) {
+    for (const propstat of successful(response)) {
+      const property = find(propstat, qname);
+      const href = property ? textOf(property, `{${DAV}}href`) : undefined;
+      if (href) return href;
+    }
+  }
+  return undefined;
+}
+
+export function error(message: string): ToolResult {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+export function json(value: unknown): ToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+interface Collection {
+  readonly name: string;
+  readonly href: string;
+}
+
+export interface DavReply {
+  readonly status: number;
+  readonly text: string;
+  readonly url: string;
+}
+
+export const PRINCIPAL_BODY =
+  `<?xml version="1.0" encoding="utf-8"?>` +
+  `<d:propfind xmlns:d="DAV:"><d:prop><d:current-user-principal/></d:prop></d:propfind>`;
+
+/**
+ * A DAV request, with the redirect policy this protocol needs.
+ *
+ * Redirects are followed by hand. `fetch`'s automatic handling would resend the
+ * Authorization header to wherever it was pointed — an app-specific password
+ * handed to whoever the Location names — and it does not reliably repeat a body
+ * for a non-standard method, which every request here has.
+ */
+export async function davRequest(
+  doFetch: typeof globalThis.fetch,
+  authorize: (request: Request) => Promise<Request>,
+  url: string,
+  method: string,
+  body?: string,
+  headers: Record<string, string> = {},
+): Promise<DavReply> {
+  let target = url;
+
+  for (let hop = 0; hop < 5; hop++) {
+    const request = await authorize(
+      new Request(target, {
+        method,
+        headers: { 'content-type': 'application/xml; charset=utf-8', ...headers },
+        ...(body ? { body } : {}),
+        redirect: 'manual',
+      }),
+    );
+
+    const response = await doFetch(request);
+
+    if (![301, 302, 307, 308].includes(response.status)) {
+      return { status: response.status, text: await response.text(), url: target };
+    }
+
+    const location = response.headers.get('location');
+    if (!location) break;
+
+    const next = new URL(location, target);
+    // iCloud relocates to a numbered partition of its own domain. Following
+    // *off* the registrable domain would hand the credential to a stranger.
+    if (next.protocol !== 'https:' || !sameSite(next.hostname, new URL(target).hostname)) {
+      throw new Error(
+        `The server redirected to ${next.origin}, which is not the host you configured. Refusing to send credentials there.`,
+      );
+    }
+
+    target = next.href;
+  }
+
+  throw new Error('Too many redirects while talking to the DAV server.');
+}
+
+
+
+/** Whether a redirect stayed within the same registrable domain. */
+export function sameSite(next: string, current: string): boolean {
+  if (next === current) return true;
+  const tail = current.split('.').slice(-2).join('.');
+  return next === tail || next.endsWith(`.${tail}`);
+}

package/src/connectivity/transports/dav/xml.ts

@@ -0,0 +1,123 @@
+import { parseXml, XmlElement, type XmlNode } from '@rgrove/parse-xml';
+
+/**
+ * Reading WebDAV's `multistatus` replies.
+ *
+ * Namespaces are resolved to `{uri}local` rather than matched by prefix,
+ * because the prefix is the server's choice and servers disagree freely:
+ * iCloud writes `<D:href>`, Fastmail `<d:href>`, Nextcloud `<href>` with a
+ * default namespace. Anything matching on `D:` works against one vendor and
+ * silently finds nothing against the next — and "found nothing" is
+ * indistinguishable from "you have no calendars".
+ *
+ * Building the request side is templates plus escaping, not a serialiser: there
+ * are four bodies, each fixed apart from a date range or a search string.
+ */
+
+/** DAV namespace URIs, as constants because they are typed wrong so easily. */
+export const DAV = 'DAV:';
+export const CALDAV = 'urn:ietf:params:xml:ns:caldav';
+export const CARDDAV = 'urn:ietf:params:xml:ns:carddav';
+
+export interface DavNode {
+  /** `{DAV:}href` — namespace URI in braces, then the local name. */
+  readonly qname: string;
+  readonly text: string;
+  /**
+   * Kept because DAV puts real answers in attributes, not only in text:
+   * `<C:comp name="VEVENT"/>` is how a collection says whether it holds events
+   * or reminders, and that distinction decides whether it is a calendar at all.
+   */
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly children: readonly DavNode[];
+}
+
+/**
+ * Parse a DAV response body.
+ *
+ * A `<!DOCTYPE` is refused outright rather than parsed. That is the entire
+ * defence against both XXE and the billion-laughs expansion, it costs one line,
+ * and no DAV server has any reason to send one.
+ */
+export function parseDav(xml: string): DavNode {
+  if (/<!DOCTYPE/i.test(xml)) {
+    throw new Error('The server sent XML with a DOCTYPE, which this client refuses to parse.');
+  }
+
+  const document = parseXml(xml, { ignoreUndefinedEntities: true });
+  const root = document.children.find((node): node is XmlElement => node instanceof XmlElement);
+  if (!root) throw new Error('The server sent XML with no root element.');
+
+  return normalise(root, new Map([['xml', 'http://www.w3.org/XML/1998/namespace']]));
+}
+
+function normalise(element: XmlElement, inherited: ReadonlyMap<string, string>): DavNode {
+  const prefixes = new Map(inherited);
+
+  for (const [name, value] of Object.entries(element.attributes)) {
+    if (name === 'xmlns') prefixes.set('', value);
+    else if (name.startsWith('xmlns:')) prefixes.set(name.slice(6), value);
+  }
+
+  const colon = element.name.indexOf(':');
+  const prefix = colon === -1 ? '' : element.name.slice(0, colon);
+  const local = colon === -1 ? element.name : element.name.slice(colon + 1);
+  const uri = prefixes.get(prefix) ?? '';
+
+  return {
+    qname: `{${uri}}${local}`,
+    text: element.text,
+    attributes: element.attributes,
+    children: element.children
+      .filter((child: XmlNode): child is XmlElement => child instanceof XmlElement)
+      .map((child) => normalise(child, prefixes)),
+  };
+}
+
+/** Every descendant with this qualified name, at any depth. */
+export function findAll(node: DavNode, qname: string): DavNode[] {
+  const found: DavNode[] = [];
+  const walk = (current: DavNode): void => {
+    if (current.qname === qname) found.push(current);
+    for (const child of current.children) walk(child);
+  };
+  walk(node);
+  return found;
+}
+
+/** The first descendant with this qualified name. */
+export function find(node: DavNode, qname: string): DavNode | undefined {
+  return findAll(node, qname)[0];
+}
+
+/** The text of the first descendant with this qualified name. */
+export function textOf(node: DavNode, qname: string): string | undefined {
+  const found = find(node, qname);
+  const text = found?.text.trim();
+  return text ? text : undefined;
+}
+
+/**
+ * Whether a `propstat` block actually succeeded.
+ *
+ * A multistatus reports per-property status, so a `<prop>` present in the reply
+ * is not a property the server *has* — a 404 propstat carries the same element
+ * names, empty. Reading those as values is how a calendar list comes back full
+ * of blanks.
+ */
+export function successful(response: DavNode): DavNode[] {
+  return findAll(response, `{${DAV}}propstat`).filter((propstat) => {
+    const status = textOf(propstat, `{${DAV}}status`) ?? '';
+    return / 2\d\d /.test(status) || status.includes('200');
+  });
+}
+
+/** Escape text destined for an XML body. */
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/src/connectivity/transports/factory.ts

@@ -0,0 +1,181 @@
+import type { AnyConnector, ProviderDefinition, ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import type { ProviderRegistry } from '#registry';
+import { basicCredential } from '#connectivity/auth/basic/index.ts';
+import { resolveUpstreamToken } from '#connectivity/auth/oauth-authcode/index.ts';
+import { createCompositeConnector } from './composite/index.ts';
+import { createDavConnector } from './dav/index.ts';
+import { createFsConnector } from './fs/index.ts';
+import { createHttpConnector } from './http/index.ts';
+import { createImapConnector } from './imap/index.ts';
+import { createLocalConnector } from './local/index.ts';
+import { createMcpConnector } from './mcp/index.ts';
+
+/**
+ * Which transport a provider gets, and one instance of it per connection.
+ *
+ * The single place that turns a declared `connector.kind` into running code —
+ * so the connectivity types are a closed set you can read off one switch, and
+ * adding one is a folder beside this file plus a case below.
+ */
+
+export interface ConnectorFactoryOptions {
+  readonly registry: ProviderRegistry;
+  readonly credentials: SecretStore;
+}
+
+/**
+ * Build connectors, memoised per provider *and* connection.
+ *
+ * The connection used to be fixed when the factory was constructed, which meant
+ * every caller built a fresh factory — and therefore a fresh cache — for every
+ * lookup, so nothing was ever reused. That went unnoticed because `mcp` and
+ * `http` are request-shaped and a redundant instance costs nothing. `imap` holds
+ * a socket, so the same bug would have meant a TLS handshake and a LOGIN per
+ * tool call, against a server that throttles exactly that.
+ *
+ * Taking the connection as an argument is what makes one factory per runtime
+ * possible, which is what makes the cache real.
+ */
+export interface ConnectorFactory {
+  (providerId: string, connectionId: string): AnyConnector | undefined;
+  /**
+   * Close every connector that holds a session.
+   *
+   * Only a stateful kind implements `close`; for the rest this is a no-op. A
+   * failure to close is swallowed — the process is going away, and a socket that
+   * cannot be shut down cleanly is not a reason to fail the command that was
+   * already finished.
+   */
+  closeAll(): Promise<void>;
+}
+
+export function connectorFactory(options: ConnectorFactoryOptions): ConnectorFactory {
+  const cache = new Map<string, AnyConnector>();
+
+  const factory = (providerId: string, connectionId: string): AnyConnector | undefined => {
+    const key = `${providerId}.${connectionId}`;
+    const cached = cache.get(key);
+    if (cached) return cached;
+
+    const entry = options.registry.get(providerId);
+    if (!entry) return undefined;
+
+    const connector = wrap(entry.definition, build(entry.manifest, entry.definition, connectionId, options));
+    if (connector) cache.set(key, connector);
+    return connector;
+  };
+
+  factory.closeAll = async (): Promise<void> => {
+    await Promise.all(
+      [...cache.values()].map(async (connector) => {
+        try {
+          await connector.close?.();
+        } catch {
+          /* see above */
+        }
+      }),
+    );
+    cache.clear();
+  };
+
+  return factory;
+}
+
+/**
+ * Layer a provider's own capabilities over a remote connector.
+ *
+ * Only when it has both, which is neither of the two common cases: `local` is
+ * already all authored code, and a manifest-only provider has nothing to layer.
+ * What is left is a remote provider carrying a handful of authored capabilities
+ * because the vendor's API can do something its document cannot describe — see
+ * `composite/index.ts`.
+ */
+function wrap(
+  definition: ProviderDefinition | undefined,
+  remote: AnyConnector | undefined,
+): AnyConnector | undefined {
+  if (!remote || !definition || definition.capabilities.length === 0) return remote;
+  if (remote.kind === 'local') return remote;
+
+  return createCompositeConnector({ definition, remote });
+}
+
+function build(
+  manifest: ProviderManifest,
+  definition: ProviderDefinition | undefined,
+  connectionId: string,
+  options: ConnectorFactoryOptions,
+): AnyConnector | undefined {
+  switch (manifest.connector.kind) {
+    case 'local':
+      return definition ? createLocalConnector(definition) : undefined;
+
+    case 'mcp':
+      return createMcpConnector({
+        endpoint: manifest.connector.endpoint,
+        accessToken: () => resolveUpstreamToken(manifest, connectionId, options.credentials),
+      });
+
+    case 'imap':
+      return createImapConnector({
+        host: manifest.connector.host,
+        port: manifest.connector.port,
+        maxBodyBytes: manifest.connector.max_body_bytes,
+        ...(manifest.setup?.troubleshooting !== undefined
+          ? { troubleshooting: manifest.setup.troubleshooting }
+          : {}),
+        // Mapped rather than passed through: the manifest is snake_case and the
+        // transport option is not, the same way `max_body_bytes` is above.
+        ...(manifest.connector.smtp
+          ? {
+              smtp: {
+                host: manifest.connector.smtp.host,
+                port: manifest.connector.smtp.port,
+                starttls: manifest.connector.smtp.starttls,
+                maxMessageBytes: manifest.connector.smtp.max_message_bytes,
+              },
+            }
+          : {}),
+        // The same seam `createMcpConnector` uses for its token: a credential
+        // arrives as a constructor option, bound to one account, because IMAP
+        // has no Request to hand an authorizer and no headers to get back.
+        credential: () => basicCredential(manifest, connectionId, options.credentials),
+      });
+
+    case 'dav':
+      // No credential option: DAV is HTTPS, so `context.authorize` attaches
+      // Basic auth and the connector never sees one.
+      return createDavConnector({
+        baseUrl: manifest.connector.base_url,
+        service: manifest.connector.service,
+        maxRangeDays: manifest.connector.max_range_days,
+        ...(manifest.setup?.troubleshooting !== undefined
+          ? { troubleshooting: manifest.setup.troubleshooting }
+          : {}),
+        // Only for the connect-time credential check and the account label;
+        // every operation still goes through `context.authorize`.
+        credential: () => basicCredential(manifest, connectionId, options.credentials),
+      });
+
+    case 'fs':
+      return createFsConnector({
+        root: manifest.connector.root,
+        maxFileBytes: manifest.connector.max_file_bytes,
+        exclude: manifest.connector.exclude,
+        ...(manifest.connector.placeholder ? { placeholder: manifest.connector.placeholder } : {}),
+      });
+
+    case 'http':
+      return createHttpConnector({
+        baseUrl: manifest.connector.base_url,
+        openapi: manifest.connector.openapi,
+        ...(manifest.connector.operations?.include?.length
+          ? { include: manifest.connector.operations.include }
+          : {}),
+        ...(manifest.connector.operations?.exclude?.length
+          ? { exclude: manifest.connector.operations.exclude }
+          : {}),
+      });
+  }
+}

package/src/connectivity/transports/fs/capabilities.ts

@@ -0,0 +1,88 @@
+import { READ_BUNDLE, WRITE_BUNDLE, type DiscoveredCapability } from '#connectivity';
+import { OPERATIONS, object, pathArgument } from './operations.ts';
+
+/** What an `fs` connection exposes, as data. Fixed — a folder is a folder. */
+export function fsCapabilities(): DiscoveredCapability[] {
+  return [
+        {
+          name: OPERATIONS.listFiles,
+          description: 'List the entries in a folder.',
+          bundle: READ_BUNDLE,
+          inputSchema: object({
+            path: pathArgument,
+            recursive: { type: 'boolean', default: false },
+            limit: { type: 'integer', minimum: 1, maximum: 500, default: 200 },
+          }),
+          target: { operation: OPERATIONS.listFiles },
+        },
+        {
+          name: OPERATIONS.searchFiles,
+          description: 'Find files by name, and optionally by the text inside them.',
+          bundle: READ_BUNDLE,
+          inputSchema: object(
+            {
+              query: { type: 'string', description: 'Matched against file names.' },
+              contains: { type: 'string', description: 'Also require this text in the file.' },
+              path: pathArgument,
+              limit: { type: 'integer', minimum: 1, maximum: 200, default: 50 },
+            },
+            ['query'],
+          ),
+          target: { operation: OPERATIONS.searchFiles },
+        },
+        {
+          name: OPERATIONS.readFile,
+          description: 'Read a text file. Binary files report their type and size instead.',
+          bundle: READ_BUNDLE,
+          inputSchema: object({ path: pathArgument }, ['path']),
+          target: { operation: OPERATIONS.readFile },
+        },
+        {
+          name: OPERATIONS.fileInfo,
+          description: 'Size, timestamps, and whether the file is downloaded from the cloud.',
+          bundle: READ_BUNDLE,
+          inputSchema: object({ path: pathArgument }, ['path']),
+          target: { operation: OPERATIONS.fileInfo },
+        },
+        {
+          name: OPERATIONS.writeFile,
+          description: 'Write a text file, creating it or replacing its contents.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object(
+            {
+              path: pathArgument,
+              content: { type: 'string' },
+              overwrite: {
+                type: 'boolean',
+                default: false,
+                description: 'Required to replace a file that already exists.',
+              },
+            },
+            ['path', 'content'],
+          ),
+          target: { operation: OPERATIONS.writeFile },
+        },
+        {
+          name: OPERATIONS.moveFile,
+          description: 'Move or rename a file or folder within the root.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object({ from: pathArgument, to: pathArgument }, ['from', 'to']),
+          target: { operation: OPERATIONS.moveFile },
+        },
+        {
+          name: OPERATIONS.createFolder,
+          description: 'Create a folder, including any missing parents.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object({ path: pathArgument }, ['path']),
+          target: { operation: OPERATIONS.createFolder },
+        },
+        {
+          name: OPERATIONS.trashFile,
+          description:
+            'Move a file to the system Trash. Recoverable — nothing here deletes permanently.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object({ path: pathArgument }, ['path']),
+          target: { operation: OPERATIONS.trashFile },
+        },
+      ];
+}