@lanes-sh/link 0.1.0

package/src/connectivity/auth/oauth-authcode/refresh.ts

@@ -0,0 +1,118 @@
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { BROKERED, BrokerError, brokerRefresh } from './broker.ts';
+import type { CredentialOAuthProvider } from './provider.ts';
+
+/** What a stored OAuth credential carries beyond the tokens themselves. */
+interface StoredTokens {
+  readonly refresh_token?: string;
+  /** An identity assertion, presented to the broker so it knows whose refresh this is. */
+  readonly id_token?: string;
+  /** Which client minted this. Absent means the profile's own. */
+  readonly authorized_via?: string;
+}
+
+export async function refreshDirectly(
+  manifest: ProviderManifest,
+  provider: CredentialOAuthProvider,
+  tokenUrl: string,
+  credentials: SecretStore,
+  fetchImpl: typeof globalThis.fetch = globalThis.fetch,
+): Promise<unknown> {
+  const existing = (await provider.tokens()) as StoredTokens | undefined;
+  const refreshToken = existing?.refresh_token;
+
+  if (!refreshToken) {
+    throw new Error(
+      `No refresh token stored for ${manifest.id}. Run: lanes link connect ${manifest.id}`,
+    );
+  }
+
+  const auth = manifest.auth.kind === 'oauth' ? manifest.auth : undefined;
+
+  // Which client issued this token is a property of the *token*, not of the
+  // profile. A refresh token minted by one client is refused by another, so an
+  // operator who registers a client of their own after the fact must not drag
+  // existing connections onto it — they keep refreshing where they were issued,
+  // and only a fresh `connect` moves them.
+  const broker = auth?.broker;
+  const brokered = broker !== undefined && existing?.authorized_via === BROKERED;
+
+  const refreshed = brokered
+    ? await viaBroker(manifest, broker.url, refreshToken, existing, fetchImpl)
+    : await viaStoredClient(manifest, auth?.app, tokenUrl, refreshToken, credentials, fetchImpl);
+
+  // `existing` first, so what the response does not mention survives it. Neither
+  // the vendor nor the broker echoes `refresh_token`, `id_token`, or
+  // `authorized_via` unless there is a new one, and dropping any of the three
+  // would leave the *next* refresh with no token, no attribution, or pointed at
+  // the wrong client.
+  await provider.saveTokens({ ...existing, ...refreshed, refresh_token: refreshToken } as never);
+  return (await provider.tokens()) as unknown;
+}
+
+async function viaBroker(
+  manifest: ProviderManifest,
+  url: string,
+  refreshToken: string,
+  existing: StoredTokens,
+  fetchImpl: typeof globalThis.fetch,
+): Promise<Record<string, unknown>> {
+  try {
+    return (await brokerRefresh(
+      url,
+      { refreshToken, ...(existing.id_token ? { idToken: existing.id_token } : {}) },
+      fetchImpl,
+    )) as Record<string, unknown>;
+  } catch (cause) {
+    // This surfaces to an agent in the middle of a request, so it must name a
+    // command the *owner* runs and nothing the agent could mistake for its own
+    // next step. Same shape as the stored-client message below, deliberately:
+    // where the credential came from is not the reader's problem here.
+    const notice = cause instanceof BrokerError && cause.notice ? `\n${cause.notice}` : '';
+    throw new Error(
+      `The credential for ${manifest.id} could not be refreshed. ` +
+        `Re-authorise with: lanes link connect ${manifest.id}\n${String(
+          cause instanceof Error ? cause.message : cause,
+        ).slice(0, 200)}${notice}`,
+    );
+  }
+}
+
+async function viaStoredClient(
+  manifest: ProviderManifest,
+  app: string | undefined,
+  tokenUrl: string,
+  refreshToken: string,
+  credentials: SecretStore,
+  fetchImpl: typeof globalThis.fetch,
+): Promise<Record<string, unknown>> {
+  const [clientId, clientSecret] = app
+    ? await Promise.all([
+        credentials.get(`${app}/client_id`),
+        credentials.get(`${app}/client_secret`),
+      ])
+    : [null, null];
+
+  const body = new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken });
+  if (clientId) body.set('client_id', clientId);
+  if (clientSecret) body.set('client_secret', clientSecret);
+
+  const response = await fetchImpl(tokenUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    // A revoked or expired refresh token is the common case here, and the fix
+    // is always the same, so say it rather than surfacing the raw grant error.
+    throw new Error(
+      `The credential for ${manifest.id} could not be refreshed (${response.status}). ` +
+        `Re-authorise with: lanes link connect ${manifest.id}\n${text.slice(0, 200)}`,
+    );
+  }
+
+  return JSON.parse(text) as Record<string, unknown>;
+}

package/src/connectivity/auth/resolve.ts

@@ -0,0 +1,61 @@
+import { credentialRefForConnection } from '#connectivity';
+import type { ProviderRegistry } from '#registry';
+import type { SecretStore } from '#secrets';
+import { resolveApiKey } from './api-key/index.ts';
+import { resolveBasic } from './basic/index.ts';
+import { resolveBearer } from './bearer/index.ts';
+import { resolveHeader } from './header/index.ts';
+import { resolveNone } from './none/index.ts';
+import { resolveUpstreamToken } from './oauth-authcode/index.ts';
+import { refuseStrategy } from './strategy/index.ts';
+import type { ResolvedCredential } from './credential.ts';
+
+/**
+ * Reading the store, once, for whichever credential type the manifest declares.
+ *
+ * One reader feeding two consumers: `authorize.ts` turns the result into
+ * headers for anything HTTP-shaped, and a non-HTTP connector takes this
+ * directly as a constructor option — IMAP has no `Request` to hand an
+ * authorizer and no headers to get back.
+ *
+ * Each method's own parsing lives in its folder, so what remains here is the
+ * dispatch. Adding a credential type is a folder and a case.
+ */
+export function credentialResolver(
+  registry: ProviderRegistry,
+  secrets: SecretStore,
+): (providerId: string, connectionId: string) => Promise<ResolvedCredential> {
+  return async (providerId, connectionId) => {
+    const manifest = registry.manifest(providerId);
+    if (!manifest) return resolveNone();
+
+    const auth = manifest.auth;
+    if (auth.kind === 'none') return resolveNone();
+
+    if (auth.kind === 'oauth') {
+      const accessToken = await resolveUpstreamToken(manifest, connectionId, secrets);
+      return accessToken ? { kind: 'oauth', accessToken } : resolveNone();
+    }
+
+    if (auth.kind === 'strategy') refuseStrategy(auth.strategy);
+
+    const ref = credentialRefForConnection(manifest, connectionId)!;
+    const value = await secrets.get(ref);
+    if (!value) {
+      throw new Error(`No credential stored at ${ref}. Run: lanes link connect ${providerId}`);
+    }
+
+    switch (auth.kind) {
+      case 'basic':
+        return resolveBasic(value, ref, providerId);
+      case 'bearer':
+        return resolveBearer(value, auth.header);
+      case 'header':
+        return resolveHeader(value, auth.header);
+      case 'api_key':
+        return resolveApiKey(value, { header: auth.header, query: auth.query });
+    }
+  };
+}
+
+export type { ResolvedCredential } from './credential.ts';

package/src/connectivity/auth/strategy/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The escape hatch: auth no declarative form should try to express.
+ *
+ * bunq generates an RSA keypair, runs a three-step handshake, signs every
+ * request, and verifies the response signature. That earns code. Nothing is
+ * registered yet, so this fails loudly rather than sending an unauthenticated
+ * request that would fail confusingly upstream.
+ */
+export function refuseStrategy(strategy: string): never {
+  throw new Error(
+    `Auth strategy "${strategy}" is not registered. ` +
+      `Strategies are the only place per-vendor code belongs; see docs/detailed/creating-a-provider.md.`,
+  );
+}

package/src/connectivity/capability.ts

@@ -0,0 +1,164 @@
+import type { z } from 'zod';
+import type { RedactionRule } from '#audit';
+import type { ProviderContext } from './context.ts';
+
+/**
+ * A capability is one tool, resource, or prompt a provider exposes.
+ *
+ * Do not make everything a tool. Use resources for read-oriented document or
+ * structured context, tools for actions and parameterised queries, prompts for
+ * reusable procedures. Decide per capability and record the reasoning in
+ * `docs/detailed/providers.md` — ADR-006.
+ */
+export type Capability = ToolCapability | ResourceCapability | PromptCapability;
+
+export interface CapabilityBase {
+  /**
+   * Unqualified name, e.g. `search`. Core qualifies it as `<provider>.<name>`
+   * — `gmail.search` — and that qualified form is what policy rules and audit
+   * events reference.
+   */
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  /**
+   * What survives into the audit log. Defaults to recording argument names and
+   * value types but no values, because a search query routinely contains the
+   * very content the caller may not be allowed to read.
+   *
+   * On the base rather than on tools alone: a resource read is dispatched with
+   * its URI as an argument, and a memory address is exactly as worth recording
+   * — and exactly as worth withholding — as a message id.
+   */
+  readonly redact?: RedactionRule;
+}
+
+export type ToolResult = {
+  readonly content: ReadonlyArray<
+    | { readonly type: 'text'; readonly text: string }
+    | { readonly type: 'resource_link'; readonly uri: string; readonly name?: string }
+  >;
+  readonly isError?: boolean;
+};
+
+export interface ToolCapability<Schema extends z.ZodType = z.ZodType> extends CapabilityBase {
+  readonly kind: 'tool';
+  /**
+   * The provider's own arguments only.
+   *
+   * Do NOT declare a `connection` argument. Core injects it, populates its enum
+   * per profile from resolved policy, and resolves it to a `ConnectionInfo`
+   * before the handler runs — so a client cannot even discover connections it
+   * has no grant for. That is ADR-001, and keeping it out of provider code is
+   * what makes one tool set scale to any number of accounts.
+   */
+  readonly inputSchema: Schema;
+  handler(input: z.infer<Schema>, context: ProviderContext): Promise<ToolResult>;
+}
+
+export interface ResourceContents {
+  readonly uri: string;
+  readonly mimeType?: string;
+  readonly text: string;
+}
+
+/**
+ * Read-oriented context addressed by a stable identifier — ADR-006.
+ *
+ * Both operations are reached through the same dispatch path tools use, so a
+ * resource read is policy-checked and audited exactly like a tool call. Core
+ * selects between them by whether it passes a `uri` argument: present means
+ * `read`, absent means `list`. Providers never see that distinction; they
+ * implement two methods.
+ */
+export interface ResourceCapability extends CapabilityBase {
+  readonly kind: 'resource';
+  /** RFC 6570 style, e.g. `example://notes/{id}`. A fixed URI is also valid. */
+  readonly uriTemplate: string;
+  readonly mimeType?: string;
+  /** Enumerate concrete resources. Omit when the space is unbounded. */
+  list?(context: ProviderContext): Promise<ReadonlyArray<{ uri: string; name: string }>>;
+  read(
+    uri: string,
+    params: Readonly<Record<string, string>>,
+    context: ProviderContext,
+  ): Promise<ResourceContents>;
+}
+
+/**
+ * A reusable procedure — the `skills` provider, and nothing else so far.
+ *
+ * The shape was fixed in M1 and left unimplemented so the primitive could not
+ * be claimed by anything else in the meantime; M4 gave it a runtime path.
+ */
+export interface PromptCapability extends CapabilityBase {
+  readonly kind: 'prompt';
+  readonly arguments?: ReadonlyArray<{
+    readonly name: string;
+    readonly description: string;
+    readonly required?: boolean;
+  }>;
+  render(args: Readonly<Record<string, string>>, context: ProviderContext): Promise<PromptResult>;
+}
+
+export interface PromptMessage {
+  readonly role: 'user' | 'assistant';
+  readonly text: string;
+}
+
+export interface PromptResult {
+  readonly messages: ReadonlyArray<PromptMessage>;
+}
+
+/** What `ResourceCapability.read` produced, as dispatch hands it back. */
+export interface ResourceResult {
+  readonly contents: ReadonlyArray<ResourceContents>;
+}
+
+/** What `ResourceCapability.list` produced. */
+export interface ResourceListResult {
+  readonly resources: ReadonlyArray<{ readonly uri: string; readonly name: string }>;
+}
+
+/**
+ * What one invocation produced, whichever primitive it was.
+ *
+ * A union rather than a widened `ToolResult` so that every existing connector —
+ * `http`, `mcp`, `imap`, `dav`, all of which serve tools only — keeps compiling
+ * unchanged: `ToolResult` is still a member, so their return type still
+ * satisfies `Connector.invoke`.
+ *
+ * Discriminated by which key is present, and the four keys are deliberately
+ * checked through the guards below rather than by hand. `content` and
+ * `contents` differ by one letter, and getting that wrong reads as an empty
+ * result rather than as a type error.
+ */
+export type CapabilityResult = ToolResult | ResourceResult | ResourceListResult | PromptResult;
+
+export function isToolResult(result: CapabilityResult): result is ToolResult {
+  return 'content' in result;
+}
+
+export function isResourceResult(result: CapabilityResult): result is ResourceResult {
+  return 'contents' in result;
+}
+
+export function isResourceListResult(result: CapabilityResult): result is ResourceListResult {
+  return 'resources' in result;
+}
+
+export function isPromptResult(result: CapabilityResult): result is PromptResult {
+  return 'messages' in result;
+}
+
+export function isTool(capability: Capability): capability is ToolCapability {
+  return capability.kind === 'tool';
+}
+
+export function isResource(capability: Capability): capability is ResourceCapability {
+  return capability.kind === 'resource';
+}
+
+export function isPrompt(capability: Capability): capability is PromptCapability {
+  return capability.kind === 'prompt';
+}

package/src/connectivity/connector.ts

@@ -0,0 +1,175 @@
+import type { ConnectorConfig, ProviderManifest } from './manifest/index.ts';
+import type { CapabilityResult, ProviderContext, ToolResult } from './index.ts';
+
+/**
+ * A connector turns a connectivity type into capabilities.
+ *
+ * Adding a *provider* means adding a manifest, never a connector. Adding a
+ * *kind* means meeting a protocol we cannot otherwise reach, which is rare and
+ * belongs in review — the test is whether the code is about a protocol or about
+ * a vendor. `http.ts` is 215 lines serving Gmail, Drive, and every REST API
+ * ever; `imap.ts` serves iCloud, Fastmail, and any Dovecot. Neither mentions a
+ * vendor. The moment a kind would, it is the wrong shape and the answer is a
+ * manifest, or at most an `AuthStrategy`.
+ *
+ * `imap` and `dav` were added because iCloud has no MCP server, no OAuth, and
+ * no REST API, and because no manifest can describe IMAP — there is no
+ * machine-readable description of it to point at. See ADR-010.
+ */
+
+/** The connectivity kinds, derived from the schema so it stays the only list. */
+export type ConnectorKind = ConnectorConfig['kind'];
+
+/**
+ * A capability as a connector reports it.
+ *
+ * `inputSchema` is **JSON Schema**, not Zod: it comes from an upstream MCP
+ * server or an OpenAPI document, neither of which we author. The MCP layer
+ * converts it at registration with the SDK's `fromJsonSchema`. Local providers
+ * still author Zod and are converted the other way.
+ */
+export interface DiscoveredCapability {
+  /** Unqualified — `search`. Core qualifies it as `<provider>.<name>`. */
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  /** Which bundle this belongs to, decided by the connector. */
+  readonly bundle?: string;
+  /**
+   * Opaque routing detail the connector needs to invoke this again — an
+   * upstream tool name, or an OpenAPI method and path. Cached alongside the
+   * capability so a cold instance can serve without re-discovering.
+   */
+  readonly target?: Record<string, unknown>;
+}
+
+/**
+ * What discovery is allowed to see: the manifest, and nothing else.
+ *
+ * Deliberately narrower than `ConnectorContext`. Discovery runs at `connect`
+ * time, *before* the connection exists in config — so there is no
+ * `ProviderContext` to hand over, and the three call sites used to fake one with
+ * `provider: undefined as never`. Narrowing the parameter says the true thing
+ * instead: what a provider exposes is a property of the provider, not of any one
+ * account. A connector needing a credential here takes it as a constructor
+ * option, the way `createMcpConnector` already takes `accessToken`.
+ */
+export interface DiscoveryContext {
+  readonly manifest: ProviderManifest;
+}
+
+export interface ConnectorContext extends DiscoveryContext {
+  /** Everything a provider is allowed to reach, unchanged from M1. */
+  readonly provider: ProviderContext;
+  /**
+   * Prepare an outbound request: attach whatever the manifest's auth kind
+   * requires. Supplied by core so a connector never handles raw credentials.
+   */
+  authorize(request: Request): Promise<Request>;
+  /** Verify a response, where the auth strategy demands it (bunq signs replies). */
+  verify?(response: Response): Promise<void>;
+}
+
+/**
+ * A connector, parameterised by what its capabilities can produce.
+ *
+ * The default is `ToolResult`, because a remote kind serves tools and nothing
+ * else: an upstream MCP server's `tools/list` and an OpenAPI document both
+ * describe operations, so there is no resource or prompt for `mcp`, `http`,
+ * `imap`, or `dav` to return. `local` is the exception and declares
+ * `Connector<CapabilityResult>`.
+ *
+ * Parameterised rather than simply widened so those four keep their precise
+ * return type — a caller of `createImapConnector` still gets a `ToolResult`
+ * back and does not have to narrow a union that can only ever hold one member.
+ * Core dispatches through `AnyConnector`, which every kind satisfies because a
+ * method's return type is covariant.
+ */
+export interface Connector<Result extends CapabilityResult = ToolResult> {
+  readonly kind: ConnectorKind;
+
+  /**
+   * Enumerate what this connection exposes.
+   *
+   * Called at `connect` time and on refresh, never on the dispatch path — the
+   * server is stateless and reads capabilities from the database cache, so a
+   * cold instance serves without a discovery round trip.
+   */
+  discover(context: DiscoveryContext): Promise<DiscoveredCapability[]>;
+
+  /** Invoke one capability. Policy has already allowed it; this only performs it. */
+  invoke(
+    capability: DiscoveredCapability,
+    args: Readonly<Record<string, unknown>>,
+    context: ConnectorContext,
+  ): Promise<Result>;
+
+  /**
+   * Whose account this connection turned out to be.
+   *
+   * For a protocol that authenticates by username there is nothing to probe:
+   * the answer is the name the *server accepted*, which is stronger than the one
+   * the operator typed. Nullary because the connector was built for exactly one
+   * connection and has no business naming another.
+   */
+  identify?(): Promise<string | null>;
+
+  /**
+   * Release a long-lived session, if this kind holds one.
+   *
+   * `mcp` and `http` are request-shaped and implement nothing here. `imap` holds
+   * a socket, because Apple throttles reconnection far harder than it throttles
+   * an open session.
+   */
+  close?(): Promise<void>;
+}
+
+/**
+ * Any connector at all — what core holds, since it dispatches to all of them.
+ *
+ * Every `Connector<ToolResult>` is one of these, so the four remote kinds need
+ * no annotation to fit.
+ */
+export type AnyConnector = Connector<CapabilityResult>;
+
+/**
+ * Pluggable auth, for what no declarative form should express.
+ *
+ * The only place per-vendor code is permitted outside `local` providers. Keep
+ * it to auth: the moment a strategy starts translating endpoints, the 612-line
+ * problem this milestone removed has come back.
+ */
+export interface AuthStrategy {
+  readonly id: string;
+
+  /**
+   * One-time setup at connect time — key generation, a handshake, whatever the
+   * vendor demands. Anything durable goes into the credential store.
+   */
+  setup?(context: AuthStrategyContext): Promise<void>;
+
+  /** Per-request: sign it, add headers, refresh a session if one has expired. */
+  authorize(request: Request, context: AuthStrategyContext): Promise<Request>;
+
+  /** Optional response check — bunq signs its replies and expects them verified. */
+  verify?(response: Response, context: AuthStrategyContext): Promise<void>;
+}
+
+export interface AuthStrategyContext {
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  /** Read-only, scoped to this connection — the same boundary providers get. */
+  readonly credentials: ProviderContext['credentials'];
+  /**
+   * Writable credential access, available **only during `setup`**.
+   *
+   * A handshake has to persist what it produces (a keypair, a session token),
+   * which per-request code must never be able to do. Absent outside setup, so
+   * the restriction is structural rather than a rule to remember.
+   */
+  readonly write?: (ref: string, value: string) => Promise<void>;
+  readonly state: ProviderContext['state'];
+  readonly log: ProviderContext['log'];
+  readonly options: Readonly<Record<string, unknown>>;
+}

package/src/connectivity/context.ts

@@ -0,0 +1,77 @@
+import type { AuditLogger } from '#audit';
+import type { ScopedSecrets } from '#secrets';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * Key/value state for one provider on one connection.
+ *
+ * Already namespaced by core before a provider receives it, so there is no key
+ * a provider can construct that reaches another provider's state or another
+ * connection's state within its own provider.
+ */
+export interface ScopedStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+
+  getJson<T>(key: string): Promise<T | null>;
+  setJson(key: string, value: unknown): Promise<void>;
+}
+
+export interface Logger {
+  debug(message: string, detail?: Record<string, unknown>): void;
+  info(message: string, detail?: Record<string, unknown>): void;
+  warn(message: string, detail?: Record<string, unknown>): void;
+  error(message: string, detail?: Record<string, unknown>): void;
+}
+
+/** The connection a capability was invoked for. */
+export interface ConnectionInfo {
+  /** Connection id, unique within the provider. e.g. `main`. */
+  readonly id: string;
+  /** Fully qualified: `gmail.main`. */
+  readonly key: string;
+  readonly displayName: string;
+  /** Validated against the provider's own `connectionSchema`. */
+  readonly config: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Everything a provider is given, and nothing else.
+ *
+ * Providers receive scoped capabilities, never raw backends. There is no
+ * `RuntimeState` here, no `SecretStore`, no config, no policy engine, and no
+ * way to reach another connection.
+ *
+ * Note what this does NOT protect against: provider code is trusted code. It
+ * runs in-process and holds its connection's credential, so a malicious
+ * provider can do anything that credential permits. There is no provider
+ * sandbox in M1. Installing a third-party provider is equivalent to running
+ * arbitrary code with access to that account, and
+ * `docs/detailed/creating-a-provider.md` says so plainly.
+ */
+export interface ProviderContext {
+  readonly connection: ConnectionInfo;
+  readonly state: ScopedStore;
+  readonly storage: BlobStore;
+  readonly credentials: ScopedSecrets;
+  readonly audit: AuditLogger;
+  readonly log: Logger;
+  /** Aborted when the client disconnects or a limit is hit. */
+  readonly signal: AbortSignal;
+  /**
+   * Attach this connection's credential to an outbound request.
+   *
+   * The same authorizer a connector is given, offered here for a provider that
+   * has to call its own vendor's API directly — a capability authored precisely
+   * because the generic transport cannot express the call. It is a
+   * connection-scoped capability rather than a raw backend, which is the line
+   * this interface draws: a provider still cannot read the credential, name a
+   * different connection, or reach a store it did not declare.
+   *
+   * Optional because `local` providers hold no third-party account and the test
+   * harness builds a context without one.
+   */
+  authorize?(request: Request): Promise<Request>;
+}