@lanes-sh/link 0.6.11 → 0.7.0

package/src/providers/untested.ts

@@ -0,0 +1,105 @@
+/**
+ * Providers nobody has connected to a real account yet.
+ *
+ * A manifest can be right in every way this repository can check — the schema
+ * validates, the spec generates registrable tools inside the budget, the scopes
+ * are described, the endpoint answered an unauthenticated probe — and still not
+ * work. What none of that proves is the part only a live account proves: that
+ * the grant is the right one, that the identity probe reads a field the vendor
+ * actually returns, that a refresh token comes back, that the tool list is worth
+ * having.
+ *
+ * So this is an honest label rather than a warning. Everything here is expected
+ * to work and is shipped in that belief; none of it has been used in anger. A
+ * provider leaves this list when somebody connects it and it does what it says.
+ *
+ * One list, and the documentation is checked against it — `src/readme.test.ts`
+ * asserts the tables mark exactly these and no others, because a status that is
+ * maintained in three places is a status that is wrong in two of them.
+ */
+export const UNTESTED_PROVIDERS: ReadonlySet<string> = new Set([
+  'airtable',
+  'algolia',
+  'amplitude',
+  'apify',
+  'asana',
+  'attio',
+  'betterstack',
+  'brightdata',
+  'buildkite',
+  'calendly',
+  'canva',
+  'circleci',
+  'clickup',
+  'close',
+  'cloudflare_bindings',
+  'cloudflare_observability',
+  'contentful',
+  'datadog',
+  'dropbox',
+  'expensify',
+  'fastmail_calendar',
+  'fastmail_contacts',
+  'fastmail_mail',
+  'figma',
+  'fireflies',
+  'flagsmith',
+  'gamma',
+  'grafana',
+  'heroku',
+  'hygraph',
+  'insightly',
+  'jam',
+  'klaviyo',
+  'mercury',
+  'microsoft_todo',
+  'miro',
+  'mixpanel',
+  'monday',
+  'mux',
+  'navan',
+  'neon',
+  'netlify',
+  'onedrive',
+  'outlook_calendar',
+  'outlook_contacts',
+  'outlook_mail',
+  'paddle',
+  'paypal',
+  'posthog',
+  'prisma',
+  'ramp',
+  'recurly',
+  'remote',
+  'replicate',
+  'resend',
+  'riverside',
+  'rootly',
+  'rudderstack',
+  'salesloft',
+  'sanity',
+  'sentry',
+  'shortcut',
+  'square',
+  'storyblok',
+  'stripe',
+  'supabase',
+  'tavily',
+  'todoist',
+  'vercel',
+  'vimeo',
+  'webflow',
+  'whimsical',
+  'wix',
+  'workable',
+  'yahoo_mail',
+  'zapier',
+  'zoho_mail',
+  'atlassian',
+  'hubspot',
+  'box',
+  'render',
+  'mailbox',
+  'nextcloud_calendar',
+  'nextcloud_contacts',
+]);

package/src/providers/vault/provider.ts

@@ -14,7 +14,7 @@ import { assertItemId, type VaultStore } from '#secrets';
  * Three properties, each of which is a decision recorded in ADR-012:
  *
  * **Tools only, never resources.** Resources are listable and cacheable, and
- * both are wrong for a secret (`docs/detailed/providers.md`).
+ * both are wrong for a secret (`https://lanes.sh/docs/link/capabilities`).
  *
  * **Per-item policy through the capability name.** Each stored item gets its own
  * read capability — `vault.get.github_token` — so `deny: [vault.get.bank]` and

package/src/providers/vercel/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Vercel registers us at connect time — nothing for an operator to set up. */
+export const vercel = defineProvider({
+  id: 'vercel',
+  name: 'Vercel',
+  description: 'Projects, deployments, build logs, and domains, via Vercel\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.vercel.com' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/vimeo/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Vimeo registers us at connect time — nothing for an operator to set up. */
+export const vimeo = defineProvider({
+  id: 'vimeo',
+  name: 'Vimeo',
+  description: 'Videos, folders, showcases, and analytics, via Vimeo\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.vimeo.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/webflow/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Webflow registers us at connect time — nothing for an operator to set up. */
+export const webflow = defineProvider({
+  id: 'webflow',
+  name: 'Webflow',
+  description: 'Sites, pages, CMS collections, and items, via Webflow\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.webflow.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/whimsical/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Whimsical registers us at connect time — nothing for an operator to set up. */
+export const whimsical = defineProvider({
+  id: 'whimsical',
+  name: 'Whimsical',
+  description: 'Boards, flowcharts, wireframes, and mind maps, via Whimsical\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.whimsical.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/wix/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Wix registers us at connect time — nothing for an operator to set up. */
+export const wix = defineProvider({
+  id: 'wix',
+  name: 'Wix',
+  description: 'Sites, stores, bookings, and CMS data, via Wix\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.wix.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/workable/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Workable registers us at connect time — nothing for an operator to set up. */
+export const workable = defineProvider({
+  id: 'workable',
+  name: 'Workable',
+  description: 'Jobs, candidates, and interviews, via Workable\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.workable.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/yahoo_mail/index.ts

@@ -0,0 +1,73 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Yahoo Mail over IMAP.
+ *
+ * Yahoo requires an app password for IMAP — the account password is refused
+ * outright, and has been since Yahoo turned off "less secure app access". The
+ * same hosts serve AOL and the other Yahoo-operated domains under their own
+ * names, which is why this is one provider rather than a family.
+ */
+export const yahooMail = defineProvider({
+  id: 'yahoo_mail',
+  name: 'Yahoo Mail',
+  description:
+    'Read, search, and send mail in a Yahoo mailbox over IMAP and SMTP, with an app password.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.mail.yahoo.com',
+    port: 993,
+    smtp: { host: 'smtp.mail.yahoo.com', port: 587, starttls: true },
+  },
+  auth: { kind: 'basic' },
+  identity: { kind: 'connector' },
+  setup: {
+    summary:
+      'Yahoo Mail uses an app password, which is not your Yahoo account password. Yahoo refuses the ' +
+      'account password for IMAP entirely, so there is no other route to a Yahoo mailbox here.',
+    docs_url: 'https://help.yahoo.com/kb/SLN15241.html',
+    steps: [
+      'Sign in at https://login.yahoo.com/account/security.',
+      'Choose "Generate app password" (it may be under "Other ways to sign in"). Name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+      'Copy the sixteen characters. Yahoo shows them once, in four groups of four; the spaces are cosmetic and it is accepted either way.',
+      'You are asked for your full address next, which is the one you sign in with.',
+    ],
+    troubleshooting:
+      'For Yahoo this is almost always the account password used where an app password belongs — Yahoo ' +
+      'refuses the account password for IMAP and reports it identically to a wrong one. Generate an app ' +
+      'password at https://login.yahoo.com/account/security and re-run: lanes link connect yahoo_mail --replace.',
+    prompts: [
+      {
+        key: 'username',
+        label: 'Yahoo address (the full email address)',
+        secret: false,
+        scope: 'connection' as const,
+        field: 'username' as const,
+      },
+      {
+        key: 'password',
+        label: 'App password (sixteen characters)',
+        secret: true,
+        scope: 'connection' as const,
+        field: 'password' as const,
+      },
+    ],
+  },
+  redact: {
+    // Never the search terms — a query is content, and "who did I email about
+    // the diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    // Identifiers only, and all of them: which mailbox, which message, which
+    // attachment. What the file turned out to be — name, size, type, digest —
+    // is recorded by the handler through `audit.annotate`, the same way the send
+    // path records what it attached.
+    get_attachment: ['mailbox', 'uid', 'message_id', 'attachment_id'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Nothing. The recipients and the body are the message, and `attachments`
+    // may literally contain a file — what was attached is recorded by the send
+    // path itself through `audit.annotate`.
+    send_message: [],
+  },
+});

package/src/providers/zapier/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Zapier registers us at connect time — nothing for an operator to set up. */
+export const zapier = defineProvider({
+  id: 'zapier',
+  name: 'Zapier',
+  description: 'Zaps, and the actions they reach across thousands of apps, via Zapier\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.zapier.com/api/mcp/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/zoho_mail/index.ts

@@ -0,0 +1,79 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Zoho Mail over IMAP.
+ *
+ * The hosts below are Zoho's global ones. An account created in a different
+ * data centre answers on a regional hostname instead — `imap.zoho.eu`,
+ * `imap.zoho.in`, `imap.zoho.com.au` — and the failure is a connection refused
+ * rather than an authentication error, which reads like the password is wrong.
+ * A manifest holds one host, so a regional account is a manifest of its own in
+ * `providers.d/`: the same two hosts with the suffix changed. `troubleshooting`
+ * below is where somebody actually hits this.
+ */
+export const zohoMail = defineProvider({
+  id: 'zoho_mail',
+  name: 'Zoho Mail',
+  description:
+    'Read, search, and send mail in a Zoho mailbox over IMAP and SMTP, with an application-specific password.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.zoho.com',
+    port: 993,
+    smtp: { host: 'smtp.zoho.com', port: 587, starttls: true },
+  },
+  auth: { kind: 'basic' },
+  identity: { kind: 'connector' },
+  setup: {
+    summary:
+      'Zoho Mail uses an application-specific password when two-factor authentication is on, which ' +
+      'is the supported way to reach IMAP. It is not your Zoho account password, and it does not expire.',
+    docs_url: 'https://www.zoho.com/accounts/help/multi-factor-authentication/application-specific-passwords.html',
+    steps: [
+      'Sign in at https://accounts.zoho.com and open Security → App Passwords.',
+      'Choose "Generate New Password" and name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+      'Copy the password Zoho shows. It is shown once.',
+      'IMAP has to be enabled for the mailbox: Zoho Mail → Settings → Mail Accounts → IMAP Access.',
+      'If your account is in a region other than the global one, the hosts differ — see the note below.',
+    ],
+    troubleshooting:
+      'If the connection is refused rather than the password rejected, the account is likely in a regional ' +
+      'data centre: imap.zoho.eu, imap.zoho.in, or imap.zoho.com.au rather than imap.zoho.com. Declare those ' +
+      'hosts in a manifest of your own under providers.d/ — see docs/detailed/creating-a-provider.md. If the ' +
+      'password is rejected, it is usually the Zoho account password used where an application-specific one ' +
+      'belongs: generate one at https://accounts.zoho.com and re-run: lanes link connect zoho_mail --replace.',
+    prompts: [
+      {
+        key: 'username',
+        label: 'Zoho address (the full email address)',
+        secret: false,
+        scope: 'connection' as const,
+        field: 'username' as const,
+      },
+      {
+        key: 'password',
+        label: 'Application-specific password',
+        secret: true,
+        scope: 'connection' as const,
+        field: 'password' as const,
+      },
+    ],
+  },
+  redact: {
+    // Never the search terms — a query is content, and "who did I email about
+    // the diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    // Identifiers only, and all of them: which mailbox, which message, which
+    // attachment. What the file turned out to be — name, size, type, digest —
+    // is recorded by the handler through `audit.annotate`, the same way the send
+    // path records what it attached.
+    get_attachment: ['mailbox', 'uid', 'message_id', 'attachment_id'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Nothing. The recipients and the body are the message, and `attachments`
+    // may literally contain a file — what was attached is recorded by the send
+    // path itself through `audit.annotate`.
+    send_message: [],
+  },
+});

package/src/secrets/document.ts

@@ -17,7 +17,7 @@ import type { BlobStore } from '#stores/blobs';
  *
  * What is *not* merged is the two stores themselves. They keep separate
  * documents, separate keys, and separate environment variables, because that is
- * the boundary `docs/detailed/security.md` is built on: one master secret reused across
+ * the boundary `https://lanes.sh/docs/link/security` is built on: one master secret reused across
  * purposes turns any single compromise into a total one. Sharing the code that
  * seals a document is the opposite of sharing the key that opens it.
  *

package/src/server/attachments.ts

@@ -1,3 +1,4 @@
+import { isHandle } from '#connectivity/mail';
 import { mergeCapabilities, type ProfileRuntime } from './mcp/index.ts';
 import type { Principal } from '#auth';
 
@@ -51,11 +52,20 @@ export interface StageOptions {
   readonly clientLabel?: string | undefined;
 }
 
-export async function stageAttachment(options: StageOptions): Promise<Response> {
+/**
+ * One path, both directions.
+ *
+ * `POST` takes bytes and gives back a handle; `GET` takes a handle and gives
+ * back the bytes. Same path, same query, same authorization, because they are
+ * the two ends of one idea and splitting them across two routes would invite
+ * the scoping to drift apart — which is the one thing that must not happen
+ * here, since the scoping is what keeps one account's files out of another's.
+ */
+export async function handleAttachments(options: StageOptions): Promise<Response> {
   const { request } = options;
 
-  if (request.method !== 'POST') {
-    return problem(405, 'Stage an attachment with POST.');
+  if (request.method !== 'POST' && request.method !== 'GET') {
+    return problem(405, 'Stage an attachment with POST, or fetch one with GET.');
   }
 
   const url = new URL(request.url);
@@ -82,7 +92,8 @@ export async function stageAttachment(options: StageOptions): Promise<Response>
 
   // The same policy that decides which connections a tool may name. Staging into
   // an account the caller cannot act on would be a write they are not permitted
-  // to make, even though nothing is sent by it.
+  // to make, even though nothing is sent by it — and fetching back out of one is
+  // a read they are not permitted to make, which matters more.
   if (!reachable(runtime, options, profileName, target)) {
     return problem(
       403,
@@ -90,6 +101,10 @@ export async function stageAttachment(options: StageOptions): Promise<Response>
     );
   }
 
+  if (request.method === 'GET') {
+    return await fetchAttachment({ options, runtime, url, providerId, connectionId, target });
+  }
+
   const bytes = await readCapped(request);
   if (!bytes) {
     return problem(413, `An attachment must be smaller than ${MAX_UPLOAD_BYTES} bytes.`);
@@ -124,6 +139,83 @@ export async function stageAttachment(options: StageOptions): Promise<Response>
   });
 }
 
+/**
+ * Handing a staged file back.
+ *
+ * The counterpart to the upload, and the thing that makes an attachment which
+ * arrived by mail reachable at all: `get_attachment` on a mail connection pulls
+ * the bytes out of the mailbox and stages them *in that same connection's*
+ * namespace, and this is where the client collects them. No provider gains
+ * reach it did not have — the bytes were already inside that account's area —
+ * and nothing crosses between two connections.
+ *
+ * The bytes go out over HTTP for the same reason they come in that way: a file
+ * in a tool result is base64 in the model's context, which for a 239 KB PDF is
+ * around 320,000 characters of something no model needs to read.
+ */
+async function fetchAttachment(input: {
+  readonly options: StageOptions;
+  readonly runtime: ProfileRuntime;
+  readonly url: URL;
+  readonly providerId: string;
+  readonly connectionId: string;
+  readonly target: string;
+}): Promise<Response> {
+  const handle = input.url.searchParams.get('handle');
+  if (!handle) {
+    return problem(400, 'Name the file to fetch, as ?handle=att_… — the handle a stage or a get_attachment returned.');
+  }
+  if (!isHandle(handle)) {
+    return problem(400, `"${handle}" is not a handle.`);
+  }
+
+  const found = await input.runtime.dispatcher.fetchStagedAttachment({
+    principal: input.options.principal,
+    providerId: input.providerId,
+    connectionId: input.connectionId,
+    handle,
+    clientLabel: input.options.clientLabel,
+  });
+
+  // One answer for absent, expired, and staged-against-another-connection. The
+  // caller can act on none of the three differently, and telling them apart is
+  // how someone probes for handles belonging to an account they cannot reach.
+  if (!found) {
+    return problem(
+      404,
+      `No staged file "${handle}" for ${input.target}. A staged file lasts 24 hours and belongs to the connection it was staged for.`,
+    );
+  }
+
+  return new Response(found.bytes, {
+    headers: {
+      'content-type': found.contentType ?? 'application/octet-stream',
+      'content-length': String(found.bytes.byteLength),
+      // `attachment` rather than `inline`: this is a file the caller asked for,
+      // and a browser rendering someone's mail attachment in the tab is not it.
+      'content-disposition': dispositionFor(found.filename),
+      // Handles are unguessable and short-lived, but a shared cache holding
+      // somebody's mail attachment is not a trade worth making.
+      'cache-control': 'no-store',
+    },
+  });
+}
+
+/**
+ * A `Content-Disposition` that survives a non-ASCII filename.
+ *
+ * RFC 6266: the bare `filename` is the fallback for old clients and must stay
+ * ASCII, and `filename*` carries the real one percent-encoded. Mail attachments
+ * are exactly where this bites — an invoice from a German sender is called
+ * `Rechnung_Kaufmännisch.pdf` and a raw header would be rejected outright.
+ */
+function dispositionFor(filename: string | null): string {
+  if (!filename) return 'attachment';
+
+  const ascii = filename.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+
 /** Whether this principal can reach that connection for anything at all. */
 function reachable(
   runtime: ProfileRuntime,
@@ -188,10 +280,42 @@ async function readCapped(request: Request): Promise<Uint8Array | null> {
  * `Content-Disposition` and stored beside the bytes, and neither wants a path.
  */
 function filenameFrom(header: string | null): string {
-  const candidate = (header ?? '').split(/[/\\]/).pop()?.trim() ?? '';
+  const candidate = decodeHeader(header ?? '').split(/[/\\]/).pop()?.trim() ?? '';
   return candidate === '' || candidate === '.' || candidate === '..' ? 'attachment' : candidate;
 }
 
+/**
+ * A header value as the bytes it actually was.
+ *
+ * An HTTP header carries bytes, and a runtime hands them back one character per
+ * byte — so a filename a client sent as UTF-8 arrives here as mojibake and is
+ * *stored* that way. `Rechnung_Kaufmännisch.pdf` became
+ * `Rechnung_Kaufmännisch.pdf` in the metadata sidecar, and stayed wrong on the
+ * way back out; it was invisible while there was no way to fetch a file back.
+ *
+ * Pure ASCII is returned untouched, which is almost every filename. Anything
+ * that is not valid UTF-8 keeps whatever it was rather than being replaced with
+ * question marks — a name we cannot decode is still the name the client chose.
+ */
+function decodeHeader(value: string): string {
+  // Nothing to do for ASCII, and a code point above 0xff means the runtime has
+  // already decoded it — reinterpreting that would be the corruption, not the fix.
+  let latin1 = false;
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code > 0xff) return value;
+    if (code > 0x7f) latin1 = true;
+  }
+  if (!latin1) return value;
+
+  try {
+    const bytes = Uint8Array.from(value, (character) => character.charCodeAt(0));
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return value;
+  }
+}
+
 function problem(status: number, message: string): Response {
   return Response.json({ error: message }, { status });
 }

package/src/server/index.ts

@@ -1,7 +1,7 @@
 import type { Authenticator } from '#auth';
 import type { Logger } from '#connectivity';
 import { capabilityIdForToolName } from '#server/mcp';
-import { ATTACHMENTS_PATH, stageAttachment } from './attachments.ts';
+import { ATTACHMENTS_PATH, handleAttachments } from './attachments.ts';
 import { allowedHostnamesFor, rebindingRefusal } from './rebinding.ts';
 import { ANY_ORIGIN, corsAware, type CorsPolicy } from './cors.ts';
 import type { Generation } from './generation.ts';
@@ -234,7 +234,7 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
         // into one named connection rather than a shared area, so a staged file
         // stays as isolated as the account it was staged for.
         if (url.pathname === ATTACHMENTS_PATH) {
-          return await stageAttachment({
+          return await handleAttachments({
             profiles: generation.profiles,
             primary: options.primary,
             principal: outcome.principal,
@@ -262,7 +262,7 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
         // whose default is `'stateless'`, so those requests are served rather
         // than refused. This check short-circuits and the refusal goes
         // unrecorded. That is the second documented exception to
-        // `audit.every-invocation` in `docs/detailed/security.md`, asserted in
+        // `audit.every-invocation` in `https://lanes.sh/docs/link/security`, asserted in
         // `index.test.ts`. Closing it means cloning and parsing the body when
         // the header is absent, which is what `stdio.ts` does for want of
         // headers.