@lanes-sh/link 0.1.0

package/src/connectivity/manifest/connector.ts

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+
+/**
+ * Connectivity types — how we reach a service.
+ *
+ * One schema per transport in `../transports/`, and the discriminated union
+ * below is the complete list. A provider picks exactly one; how it
+ * *authenticates* is the other axis entirely (`./auth.ts`), which is what lets
+ * iCloud speak IMAP with a password while Gmail speaks HTTP with OAuth and
+ * neither costs the other any code.
+ */
+
+/**
+ * Proxy an upstream MCP server. Capabilities are **discovered**, never declared
+ * — the server is the source of truth for what it exposes.
+ */
+export const mcpConnectorSchema = z.object({
+  kind: z.literal('mcp'),
+  endpoint: z.url(),
+});
+
+/**
+ * A REST API described by OpenAPI. Operations become capabilities mechanically,
+ * so a service without an MCP server still costs no translation code.
+ */
+export const httpConnectorSchema = z.object({
+  kind: z.literal('http'),
+  base_url: z.url(),
+  /** URL or workspace-relative path to an OpenAPI 3.x document. */
+  openapi: z.string().min(1),
+  /**
+   * Glob filters on operationId, path, or tag.
+   *
+   * Not optional in spirit: a large spec yields hundreds of operations, which
+   * is a tool list no agent can reason over. For an `http` connector,
+   * "everything discovered" means everything selected here.
+   */
+  operations: z
+    .object({
+      include: z.array(z.string()).default([]),
+      exclude: z.array(z.string()).default([]),
+    })
+    .optional(),
+});
+
+/**
+ * A mailbox over IMAP4rev1, and optionally SMTP submission.
+ *
+ * Vendor-neutral: iCloud, Fastmail, and a company Dovecot are the same handful
+ * of fields. Unlike `http` there is no document to read — IMAP describes its
+ * *extensions* through CAPABILITY but never its operations — so the capability
+ * set belongs to the connector rather than to the manifest.
+ */
+export const imapConnectorSchema = z.object({
+  kind: z.literal('imap'),
+  host: z.string().min(1),
+  port: z.number().int().min(1).max(65535).default(993),
+  smtp: z
+    .object({
+      host: z.string().min(1),
+      port: z.number().int().min(1).max(65535).default(587),
+      /** 587 upgrades in-band; 465 is implicit TLS. Either way TLS is required. */
+      starttls: z.boolean().default(true),
+      /**
+       * Largest message this host will accept, encoded, in bytes.
+       *
+       * A server limit the provider declares, like `max_range_days` above.
+       * Attachments are base64 in the wire format, so the usable weight of the
+       * files themselves is about three quarters of this — the send path derives
+       * that rather than making a caller do the arithmetic.
+       *
+       * The default is iCloud's 20 MB, which is also roughly where the common
+       * hosts sit. Worth checking one is refused *before* dialling: a message
+       * rejected part-way through `DATA` reads as a network failure, and a caller
+       * that cannot tell the difference tries again.
+       */
+      max_message_bytes: z
+        .number()
+        .int()
+        .positive()
+        .max(157_286_400)
+        .default(20 * 1024 * 1024),
+    })
+    .optional(),
+  /**
+   * How much of a body one call may return.
+   *
+   * A 40 MB newsletter is not something an agent's context survives, and where
+   * to draw that line has to be our decision rather than whatever the message
+   * happens to weigh.
+   */
+  max_body_bytes: z.number().int().positive().max(4_194_304).default(262_144),
+});
+
+/**
+ * CalDAV and CardDAV — HTTPS, but XML under PROPFIND and REPORT, which no
+ * OpenAPI document describes, so `http` cannot serve it. Auth is ordinary Basic,
+ * which is the payoff for keeping auth orthogonal to connectivity.
+ */
+export const davConnectorSchema = z.object({
+  kind: z.literal('dav'),
+  /** Where discovery begins; RFC 6764 well-known paths are tried under it. */
+  base_url: z.url(),
+  service: z.enum(['caldav', 'carddav']),
+  /**
+   * Longest `list_events` window this server will answer.
+   *
+   * A server limit, so the provider declares it rather than the transport
+   * assuming it. iCloud rejects a wider range than a year; every server slows
+   * down over one, which is why there is a default rather than no bound.
+   */
+  max_range_days: z.number().int().positive().max(3650).default(366),
+});
+
+/**
+ * A directory on the machine this runs on.
+ *
+ * Vendor-neutral: iCloud Drive is a manifest pointing at its folder, and the
+ * same connector serves Dropbox, Syncthing, or a project directory. There is no
+ * credential — access to a Mac's iCloud Drive is a TCC grant bound to a binary
+ * on that Mac, not a token, so there is nothing to store and nothing that could
+ * be carried to another machine. See ADR-011.
+ */
+export const fsConnectorSchema = z.object({
+  kind: z.literal('fs'),
+  /** May start with `~`. Everything reachable is under it, symlinks included. */
+  root: z.string().min(1),
+  max_file_bytes: z.number().int().positive().max(4_194_304).default(262_144),
+  /** Extra names never listed or read, on top of the built-in refusals. */
+  exclude: z.array(z.string()).default([]),
+  /**
+   * How this folder's sync client marks a file it has not downloaded.
+   *
+   * macOS represents a dataless iCloud Drive file as a hidden sibling named
+   * `.<name>.icloud`, so a listing shows a name that cannot be read and a read
+   * returns a few hundred bytes of plist — which looks like a corrupt file
+   * rather than an absent one. A folder synced by something else uses a
+   * different convention, or none.
+   *
+   * Declared rather than assumed: this is the one place the word "icloud" would
+   * otherwise be hard-coded into a transport that also serves Dropbox,
+   * Syncthing, and a plain project directory. `hint` is the remedy, in the
+   * provider's own words, because "run brctl" is advice only Apple's answer can
+   * give.
+   */
+  placeholder: z
+    .object({
+      suffix: z.string().min(1),
+      hint: z.string().optional(),
+    })
+    .optional(),
+});
+
+/** Our own code — `example`, and the owner layer. */
+export const localConnectorSchema = z.object({
+  kind: z.literal('local'),
+});
+
+export const connectorSchema = z.discriminatedUnion('kind', [
+  mcpConnectorSchema,
+  httpConnectorSchema,
+  imapConnectorSchema,
+  davConnectorSchema,
+  fsConnectorSchema,
+  localConnectorSchema,
+]);
+
+export type ConnectorConfig = z.infer<typeof connectorSchema>;

package/src/connectivity/manifest/credential-ref.ts

@@ -0,0 +1,73 @@
+import type { ProviderManifest } from './provider.ts';
+
+/**
+ * Where this provider keeps the credential for one connection.
+ *
+ * The single authority, because there used to be two that disagreed: reconcile
+ * derived `<provider>/<id>` and never read the manifest, while the request
+ * authorizer read the manifest and never derived. A provider declaring
+ * `credential_ref: mything/api_key` was therefore reported unauthorized forever
+ * — `doctor` told you to run `connect`, and `connect` did not help.
+ *
+ * Four cases, in precedence order. The caller applies a fifth ahead of them all:
+ * a `credential_ref` on the *connection* is a hand placement and wins outright.
+ */
+export function credentialRefForConnection(
+  manifest: ProviderManifest,
+  connectionId: string,
+): string | undefined {
+  const auth = manifest.auth;
+
+  if (auth.kind === 'none') return undefined;
+
+  // OAuth tokens are always per provider. `app` names the shared *client*, not
+  // where tokens land: Gmail and Drive authorise against one Google client but
+  // hold separate tokens, because they were granted different scopes, and
+  // pointing both at one ref would have the second connect silently narrow the
+  // first.
+  if (auth.kind === 'oauth') return `${manifest.id}/${connectionId}`;
+
+  if (auth.kind === 'strategy') return auth.credential_ref ?? `${manifest.id}/${connectionId}`;
+
+  if (auth.credential_ref) return auth.credential_ref;
+  return `${auth.app ?? manifest.id}/${connectionId}`;
+}
+
+/**
+ * Which of this connection's references get written while serving a request,
+ * rather than only by a command the operator ran.
+ *
+ * Nothing about a credential says whether it is rewritten in flight, and the
+ * one place that knows — `CredentialOAuthProvider` — keeps its refs private.
+ * So a deployed revision was granted read on the store and write on nothing,
+ * which held right up until an access token expired: the refresh persists, and
+ * the request that triggered it failed on a store it was only allowed to read.
+ *
+ * Kept beside `credentialRefForConnection` because it is the same question
+ * asked for a different purpose, and answering it two files apart is how those
+ * two disagreed the first time. `deployments/grants.test.ts` pins this against
+ * what a deploy actually binds.
+ */
+export function rotatableCredentialRefs(
+  manifest: ProviderManifest,
+  connectionId: string,
+): readonly string[] {
+  const auth = manifest.auth;
+  if (auth.kind !== 'oauth') return [];
+
+  // The token blob, rewritten by `saveTokens` on every refresh. Always, and it
+  // is the one that matters: this is the hot path of an ordinary read.
+  const refs = [`${manifest.id}/${connectionId}`];
+
+  // A dynamically registered client, rewritten by `saveClientInformation` if
+  // the SDK ever re-registers mid-flight. Rare enough that it has never been
+  // seen, and unbound it fails exactly the same way — the cost of listing it is
+  // one binding on a secret that already exists.
+  //
+  // Never for `manual`: that client is the operator's, shared across every
+  // connection using the same `oauth_apps` entry, and a revision has no
+  // business rewriting it.
+  if (auth.registration !== 'manual') refs.push(`${manifest.id}/client`);
+
+  return refs;
+}

package/src/connectivity/manifest/identity.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+/**
+ * How to find out *whose* account was just authorised.
+ *
+ * Without this a config file says `Gmail main2`, which cannot answer the only
+ * question anyone asks of a connection list — which mailbox is this? The answer
+ * has to come from the provider, because it is the only party that knows, and
+ * it has to be declarative, or every vendor costs code again.
+ *
+ * Three sources cover everything we have met:
+ *
+ * - `http` — a GET returning JSON, for a vendor whose MCP server exposes no
+ *   identity tool. Gmail answers `users/me/profile` with `emailAddress` under
+ *   scopes we already hold, so this costs no extra consent.
+ * - `tool` — call a capability on the upstream MCP server and read a field of
+ *   the result. Linear's `get_workspace` is exactly this.
+ * - `connector` — the connector already knows, so ask it. A protocol that
+ *   authenticates by username has nothing to probe: the answer is the name the
+ *   *server accepted*, which is a stronger claim than the one the operator
+ *   typed, and there is no endpoint to GET for it.
+ *
+ * `field` is a dotted path. Resolution is best-effort by design: a provider with
+ * no identity block, or one whose probe fails, falls back to asking the
+ * operator. A connection is worth labelling, never worth blocking on.
+ */
+export const identitySchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('http'),
+    url: z.url(),
+    /** Dotted path into the JSON body, e.g. `emailAddress` or `user.emailAddress`. */
+    field: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal('tool'),
+    tool: z.string().min(1),
+    field: z.string().min(1),
+    arguments: z.record(z.string(), z.unknown()).default({}),
+  }),
+  z.object({ kind: z.literal('connector') }),
+]);
+
+export type IdentityDeclaration = z.infer<typeof identitySchema>;

package/src/connectivity/manifest/index.ts

@@ -0,0 +1,46 @@
+/**
+ * The provider declaration format, one file per section.
+ *
+ * It was one 513-line file, which hid the shape of the thing it describes: a
+ * manifest is a *connectivity type* plus an *auth method* plus the operator-
+ * facing text around them, and those are the two axes the whole design rests
+ * on. `connector.ts` and `auth.ts` are now the same size and sit side by side,
+ * which is what the sentence "auth is orthogonal to connectivity" looks like
+ * when the files agree with it.
+ */
+
+export {
+  connectorSchema,
+  davConnectorSchema,
+  fsConnectorSchema,
+  httpConnectorSchema,
+  imapConnectorSchema,
+  localConnectorSchema,
+  mcpConnectorSchema,
+  type ConnectorConfig,
+} from './connector.ts';
+
+export {
+  authNoneSchema,
+  authBrokerSchema,
+  authOAuthSchema,
+  authSchema,
+  authStrategySchema,
+  authTokenSchema,
+  type AuthBroker,
+  type AuthConfig,
+} from './auth.ts';
+
+export { setupPromptSchema, setupSchema, type SetupDeclaration, type SetupPrompt } from './setup.ts';
+export { READ_BUNDLE, WRITE_BUNDLE, bundleSchema, type ScopeBundle } from './bundles.ts';
+export { identitySchema, type IdentityDeclaration } from './identity.ts';
+export { credentialRefForConnection, rotatableCredentialRefs } from './credential-ref.ts';
+export {
+  RESERVED_PROVIDER_IDS,
+  defineProvider,
+  providerManifestSchema,
+  type ProviderManifest,
+} from './provider.ts';
+
+export type { SetupRequirement, SetupNeeds } from './requirements.ts';
+export { setupRequirements, UNNAMED_ID } from './requirements.ts';

package/src/connectivity/manifest/primitives.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/** Provider ids, capability names, app names: lowercase, digits, underscores. */
+export const identifier = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]*$/, 'must be lowercase letters, digits, and underscores');
+
+/**
+ * A pointer into the secret store, never a value.
+ *
+ * The pattern is what stops a manifest carrying the secret itself. A literal
+ * API key has no `/` in it, so it fails here rather than being written to a
+ * config file that someone later commits.
+ */
+export const credentialRef = z
+  .string()
+  .regex(
+    /^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)+$/,
+    'must be a credential reference like "bunq/api_key", not a literal value',
+  );

package/src/connectivity/manifest/provider.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+import { authSchema } from './auth.ts';
+import { bundleSchema } from './bundles.ts';
+import { connectorSchema } from './connector.ts';
+import { identitySchema } from './identity.ts';
+import { identifier } from './primitives.ts';
+import { setupSchema } from './setup.ts';
+
+/**
+ * A provider manifest.
+ *
+ * A provider is a *declaration*, not a package: a connectivity type plus auth
+ * configuration. `providers/gmail` was 612 lines of hand-written endpoint
+ * translation; the same integration is now roughly fifteen lines of data.
+ *
+ * The same schema serves two callers, deliberately:
+ *
+ *   - built-ins, written as typed TS modules under `#providers/` and validated
+ *     at import
+ *   - the profile's own manifests in `data/<profile>/providers.d/*.yaml`, validated on load
+ *
+ * That second one is the scalability claim. A service nobody has integrated is
+ * a YAML file the operator writes, not a pull request they wait on.
+ */
+export const providerManifestSchema = z.object({
+  id: identifier,
+  name: z.string().min(1),
+  version: z.string().default('1.0.0'),
+  description: z.string().default(''),
+
+  connector: connectorSchema,
+  auth: authSchema.default({ kind: 'none' }),
+  setup: setupSchema.optional(),
+  bundles: z.array(bundleSchema).optional(),
+  /** How to label a connection with the account it actually belongs to. */
+  identity: identitySchema.optional(),
+
+  /**
+   * Per-capability audit redaction: capability name → argument keys worth
+   * recording. Everything unlisted is reduced to a type marker.
+   *
+   * The default is to withhold every value, which is the only safe default when
+   * we did not author the capability and cannot know what is sensitive.
+   */
+  redact: z.record(z.string(), z.array(z.string())).optional(),
+
+  /**
+   * Per-capability prose appended to a generated description: capability name →
+   * what the vendor's own wording leaves out.
+   *
+   * Keyed exactly like `redact`, and for a related reason. A generated tool
+   * describes its *arguments* faithfully and its *meaning* not at all, because
+   * the vendor wrote the document for someone who already knows the product.
+   * Where a capability is the answer to a question nothing about it mentions —
+   * an operation whose enum of magic strings is the whole feature, or a job that
+   * lives on a different provider entirely — that fact has to be sayable
+   * somewhere, and the only somewhere a model reads is the description.
+   *
+   * Appended rather than replacing, so a vendor improving their own wording is
+   * not silently discarded.
+   */
+  hints: z.record(z.string(), z.string()).optional(),
+});
+
+export type ProviderManifest = z.infer<typeof providerManifestSchema>;
+
+/** Provider ids reserved for the owner layer. */
+export const RESERVED_PROVIDER_IDS: readonly string[] = ['memory', 'skills', 'vault', 'setup'];
+
+/**
+ * Validate a manifest, with the cross-field rules the schema alone cannot
+ * express.
+ *
+ * These stay here rather than in the section files precisely because they span
+ * sections: a `dav` connector constrains the *auth* kind, an `oauth` block with
+ * manual registration constrains *setup*. A rule about one section alone
+ * belongs in that section's schema; everything left over is here, which is a
+ * short list and should stay one.
+ *
+ * Built-ins call this at import so a malformed provider fails there rather than
+ * at first use; the YAML loader calls it too.
+ */
+export function defineProvider(input: unknown): ProviderManifest {
+  const parsed = providerManifestSchema.safeParse(input);
+  if (!parsed.success) {
+    const where = parsed.error.issues
+      .map((issue) => `  ${issue.path.join('.') || '<root>'}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Invalid provider manifest:\n${where}`);
+  }
+
+  const manifest = parsed.data;
+
+  if (manifest.auth.kind === 'oauth' && manifest.auth.registration === 'manual') {
+    if (!manifest.auth.app) {
+      throw new Error(
+        `Provider "${manifest.id}": OAuth with registration "manual" needs an "app" naming the oauth_apps entry that holds the client.`,
+      );
+    }
+    // Prompts are required only when asking is the *only* way to get a client.
+    // A broker is the other way, so a provider that declares one and no prompts
+    // simply has no bring-your-own path — a legal thing to be. The CLI is where
+    // that absence becomes visible, by refusing the flag and saying why.
+    if (!manifest.auth.broker && (!manifest.setup || manifest.setup.prompts.length === 0)) {
+      throw new Error(
+        `Provider "${manifest.id}": OAuth with registration "manual" requires the operator to supply a client, so it must declare setup prompts. Otherwise there is no way to learn what to provide.`,
+      );
+    }
+  }
+
+  if (manifest.auth.kind === 'oauth' && manifest.auth.broker) {
+    if (manifest.auth.registration !== 'manual' || !manifest.auth.app) {
+      throw new Error(
+        `Provider "${manifest.id}": a broker supplies a pre-registered client, so auth must declare registration "manual" and an "app" naming the oauth_apps entry that overrides it.`,
+      );
+    }
+    // An MCP provider hands the exchange to the SDK, which posts to the token
+    // endpoint with whatever `clientInformation()` returned. There is no seam
+    // to route that through a broker without reimplementing its auth path, so
+    // this is refused at definition rather than discovered after consent.
+    if (manifest.connector.kind === 'mcp') {
+      throw new Error(
+        `Provider "${manifest.id}": an mcp connector runs the exchange through the SDK, which cannot route it through a broker. Register a client (registration "manual") or use dynamic registration.`,
+      );
+    }
+    if (!manifest.auth.authorize_url) {
+      throw new Error(
+        `Provider "${manifest.id}": a broker performs the exchange, but the browser still goes to the vendor, so auth.authorize_url is required.`,
+      );
+    }
+  }
+
+  if (
+    (manifest.auth.kind === 'bearer' ||
+      manifest.auth.kind === 'api_key' ||
+      manifest.auth.kind === 'header' ||
+      manifest.auth.kind === 'basic') &&
+    manifest.auth.app &&
+    manifest.auth.credential_ref
+  ) {
+    throw new Error(
+      `Provider "${manifest.id}": auth declares both "app" and "credential_ref", which contradict. ` +
+        `"app" means one secret per account shared across a vendor's providers; "credential_ref" means one secret shared across every account. Pick the one that is true.`,
+    );
+  }
+
+  for (const prompt of manifest.setup?.prompts ?? []) {
+    if (prompt.scope === 'shared' && !prompt.credential_ref) {
+      throw new Error(
+        `Provider "${manifest.id}": setup prompt "${prompt.key}" is shared across accounts, so it must name the credential_ref it writes to.`,
+      );
+    }
+    if (prompt.scope === 'connection' && prompt.credential_ref) {
+      throw new Error(
+        `Provider "${manifest.id}": setup prompt "${prompt.key}" is per-account, so its credential_ref derives and must not be declared — it would name a connection that does not exist yet.`,
+      );
+    }
+  }
+
+  if (manifest.auth.kind === 'basic') {
+    const perAccount = (manifest.setup?.prompts ?? []).filter((p) => p.scope === 'connection');
+    if (perAccount.length > 0) {
+      const has = (field: string): number => perAccount.filter((p) => p.field === field).length;
+      if (has('username') !== 1 || has('password') !== 1) {
+        throw new Error(
+          `Provider "${manifest.id}": basic auth stores "username:password", so it needs exactly one prompt with field "username" and one with field "password".`,
+        );
+      }
+    }
+  }
+
+  if (
+    (manifest.connector.kind === 'imap' || manifest.connector.kind === 'dav') &&
+    manifest.auth.kind !== 'basic'
+  ) {
+    // Every mail and DAV host that matters issues an app password and expects
+    // it over Basic. OAuth for these exists — Apple shipped one in Oct 2025 —
+    // but is partner-gated with no published scopes, so declaring it would be a
+    // manifest that validates and then cannot authenticate. Fail here instead.
+    throw new Error(
+      `Provider "${manifest.id}": a ${manifest.connector.kind} connector authenticates with a username and password, so it must declare auth "basic".`,
+    );
+  }
+
+  if (manifest.connector.kind === 'fs' && manifest.auth.kind !== 'none') {
+    // Nothing to authenticate to. The permission is the operating system's, held
+    // against the process, and there is no credential to store or to leak.
+    throw new Error(
+      `Provider "${manifest.id}": an fs connector reads a local folder and holds no account, so it must declare auth "none".`,
+    );
+  }
+
+  if (manifest.connector.kind === 'local' && manifest.auth.kind !== 'none') {
+    throw new Error(
+      `Provider "${manifest.id}": a local connector runs our own code and holds no third-party account, so it must declare auth "none".`,
+    );
+  }
+
+  const names = new Set<string>();
+  for (const bundle of manifest.bundles ?? []) {
+    if (names.has(bundle.name)) {
+      throw new Error(`Provider "${manifest.id}" declares bundle "${bundle.name}" twice`);
+    }
+    names.add(bundle.name);
+  }
+
+  return manifest;
+}