@lanes-sh/link 0.1.0

package/src/connectivity/mail/nodemailer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Types for the sliver of nodemailer this codebase uses.
+ *
+ * Declared here rather than by adding `@types/nodemailer`, which is a large
+ * surface tracking its own version and would be a second dependency to keep
+ * honest — in a repository that has six, holds live credentials, and enforces a
+ * release-age floor for exactly that reason. What we call is a few fields wide
+ * and stable; if that stops being true, this file fails to compile, which is the
+ * behaviour we want.
+ *
+ * Moved here from `transports/imap/` when a second caller appeared: an HTTP mail
+ * API needs the same composed bytes SMTP does, so composition outgrew the
+ * transport that first needed it.
+ */
+declare module 'nodemailer' {
+  interface Envelope {
+    from: string;
+    to: string[];
+  }
+
+  /**
+   * One attachment. `content` takes the raw bytes — nodemailer picks the
+   * transfer encoding and wraps base64 at 76 columns per RFC 2045 §6.8, which is
+   * the kind of detail that corrupts a PDF quietly when hand-rolled.
+   */
+  interface Attachment {
+    filename?: string;
+    content?: Buffer | Uint8Array | string;
+    contentType?: string;
+    encoding?: string;
+    cid?: string;
+  }
+
+  /** A display name plus an address. Nodemailer encodes the name if it needs it. */
+  interface Address {
+    name: string;
+    address: string;
+  }
+
+  interface Message {
+    from?: string | Address;
+    to?: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject?: string;
+    text?: string;
+    html?: string;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: Attachment[];
+    /** A pre-composed RFC 822 message, sent verbatim. */
+    raw?: Buffer | Uint8Array;
+    envelope?: Envelope;
+  }
+
+  interface SentInfo {
+    messageId: string;
+    /** Present with `streamTransport` + `buffer`: the composed message. */
+    message: Buffer;
+  }
+
+  interface Transport {
+    sendMail(message: Message): Promise<SentInfo>;
+    close(): void;
+  }
+
+  interface TransportOptions {
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    requireTLS?: boolean;
+    auth?: { user: string; pass: string };
+    /** Compose without sending, which is how the Sent copy stays identical. */
+    streamTransport?: boolean;
+    buffer?: boolean;
+  }
+
+  const nodemailer: {
+    createTransport(options: TransportOptions): Transport;
+  };
+
+  export default nodemailer;
+}

package/src/connectivity/mail/staging.ts

@@ -0,0 +1,143 @@
+import { randomBytes } from 'node:crypto';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * Staged attachments — bytes handed to the endpoint out of band, then named by
+ * an opaque handle.
+ *
+ * This is the source that survives the endpoint not being on the caller's
+ * machine. A `path` means nothing to a container, so on a hosted deployment the
+ * bytes have to arrive some other way, and MCP offers none: there is no
+ * client-to-server binary channel in any released version of the protocol, and
+ * `roots` never carried bytes even before it was deprecated. Every serious
+ * treatment of the problem lands on the same shape — upload out of band, get a
+ * handle, pass the handle as an ordinary argument — which is also what the
+ * protocol's own draft file-transfer proposal settles on.
+ *
+ * Two blobs per handle rather than one framed payload: `BlobStore.get` returns
+ * bytes and nothing else, so the filename and type live in a sidecar and the
+ * payload stays byte-exact.
+ */
+
+export const STAGED_PREFIX = 'attachments/';
+
+export const stagedBytesKey = (handle: string): string => `${STAGED_PREFIX}${handle}`;
+export const stagedMetaKey = (handle: string): string => `${STAGED_PREFIX}${handle}.json`;
+
+/** How long a staged file stays fetchable. Long enough to compose a mail around. */
+export const STAGED_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Handles are checked against this before they reach the store.
+ *
+ * `assertSafeKey` would already reject traversal, but a caller-supplied handle
+ * deserves a readable refusal rather than an internal invariant surfacing as a
+ * tool error.
+ */
+const HANDLE = /^[A-Za-z0-9_-]{1,128}$/;
+
+export interface StagedMetadata {
+  readonly filename?: string;
+  readonly content_type?: string;
+  readonly sha256?: string;
+  readonly expires_at?: number;
+}
+
+export interface StagedFile {
+  readonly bytes: Uint8Array;
+  readonly filename: string | null;
+  readonly contentType: string | null;
+}
+
+export function isHandle(value: string): boolean {
+  return HANDLE.test(value);
+}
+
+/** `att_` plus 128 bits, which is unguessable and still fits on one line. */
+export function newHandle(): string {
+  return `att_${randomBytes(16).toString('hex')}`;
+}
+
+export async function putStaged(
+  storage: BlobStore,
+  input: {
+    readonly handle: string;
+    readonly bytes: Uint8Array;
+    readonly metadata: StagedMetadata;
+  },
+): Promise<void> {
+  await storage.put(stagedBytesKey(input.handle), input.bytes, {
+    contentType: input.metadata.content_type ?? 'application/octet-stream',
+  });
+  await storage.put(
+    stagedMetaKey(input.handle),
+    new TextEncoder().encode(JSON.stringify(input.metadata)),
+    { contentType: 'application/json' },
+  );
+}
+
+/** Null for both "never staged" and "staged and expired" — the caller cannot act on the difference. */
+export async function getStaged(
+  storage: BlobStore,
+  handle: string,
+): Promise<StagedFile | null> {
+  if (!isHandle(handle)) throw new Error(`"${handle}" is not a handle.`);
+
+  const bytes = await storage.get(stagedBytesKey(handle));
+  if (!bytes) return null;
+
+  const meta = await storage.get(stagedMetaKey(handle));
+  if (!meta) return { bytes, filename: null, contentType: null };
+
+  let parsed: StagedMetadata;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(meta)) as StagedMetadata;
+  } catch {
+    // Unreadable sidecar. The payload is still the payload, so serve it rather
+    // than losing a file to a corrupt metadata write.
+    return { bytes, filename: null, contentType: null };
+  }
+
+  if (parsed.expires_at !== undefined && parsed.expires_at < Date.now()) return null;
+
+  return {
+    bytes,
+    filename: parsed.filename ?? null,
+    contentType: parsed.content_type ?? null,
+  };
+}
+
+/**
+ * Drop everything past its expiry.
+ *
+ * Swept on write rather than on a timer: there is no scheduler in this process,
+ * and staging is the only thing that creates the garbage, so the moment someone
+ * stages a file is both the cheapest and the most reliable time to clear the
+ * last batch.
+ */
+export async function sweepStaged(storage: BlobStore): Promise<number> {
+  const now = Date.now();
+  let removed = 0;
+
+  for (const blob of await storage.list(STAGED_PREFIX)) {
+    if (!blob.key.endsWith('.json')) continue;
+
+    const meta = await storage.get(blob.key);
+    if (!meta) continue;
+
+    let expiresAt: number | undefined;
+    try {
+      expiresAt = (JSON.parse(new TextDecoder().decode(meta)) as StagedMetadata).expires_at;
+    } catch {
+      continue;
+    }
+    if (expiresAt === undefined || expiresAt >= now) continue;
+
+    const handle = blob.key.slice(STAGED_PREFIX.length, -'.json'.length);
+    await storage.delete(stagedBytesKey(handle));
+    await storage.delete(blob.key);
+    removed += 1;
+  }
+
+  return removed;
+}

package/src/connectivity/mail/url.ts

@@ -0,0 +1,301 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+/**
+ * Fetching bytes from a URL a caller named, without becoming an SSRF gadget.
+ *
+ * This is the one attachment source that adds an attack surface rather than just
+ * a capability, and the threat model is concrete rather than theoretical: an
+ * agent reads a hostile email, the email says "attach the file at this URL", and
+ * the endpoint obliges. Deployed on Cloud Run the interesting target is one hop
+ * away — `169.254.169.254` hands out the service account token to anything that
+ * asks it.
+ *
+ * Four rules, in order of how much they buy:
+ *
+ *   1. HTTPS only. Plaintext to a named host is not a use case worth the hole.
+ *   2. Resolve the hostname and check **every** address it answers with, not the
+ *      first. A name with one public and one private A record would otherwise
+ *      pass a check and then connect wherever the OS felt like.
+ *   3. Do not follow redirects implicitly. Each hop is a fresh URL that has to
+ *      pass the same checks, because a public host redirecting to `127.0.0.1` is
+ *      the standard bypass.
+ *   4. Cap the body while reading it, not by trusting `Content-Length`.
+ *
+ * What this deliberately does not do is parse IP literals by hand. MCP's own
+ * security guidance is blunt that custom parsers miss octal, hex and
+ * IPv4-mapped-IPv6 encodings, so the only IPs classified here are ones `isIP`
+ * has already accepted as canonical or `dns.lookup` produced — an octal literal
+ * like `0177.0.0.1` is not a valid address, so it falls through to name
+ * resolution and fails there.
+ *
+ * Known residual risk: a name could resolve to a safe address during the check
+ * and a hostile one during the connection. Closing that needs the connection
+ * pinned to the address we validated, which means owning the socket — `fetch`
+ * does not expose it, and rewriting the URL to the literal IP would break TLS
+ * verification, trading a narrow race for a broken one. Recorded rather than
+ * hidden.
+ */
+
+const MAX_REDIRECTS = 3;
+
+export interface FetchedFile {
+  readonly bytes: Uint8Array;
+  readonly contentType: string | null;
+  readonly filename: string | null;
+}
+
+export type AddressLookup = (hostname: string) => Promise<readonly string[]>;
+
+const resolveAddresses: AddressLookup = async (hostname) => {
+  if (isIP(hostname) !== 0) return [hostname];
+  const answers = await lookup(hostname, { all: true, verbatim: true });
+  return answers.map((answer) => answer.address);
+};
+
+export async function fetchFromUrl(input: {
+  readonly url: string;
+  readonly maxBytes: number;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly addresses?: AddressLookup;
+  readonly signal?: AbortSignal | undefined;
+}): Promise<FetchedFile> {
+  const doFetch = input.fetch ?? globalThis.fetch;
+  const addresses = input.addresses ?? resolveAddresses;
+
+  let target = await checkedUrl(input.url, addresses);
+
+  for (let hop = 0; ; hop += 1) {
+    const response = await doFetch(target.href, {
+      redirect: 'manual',
+      headers: { accept: '*/*' },
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) throw new Error(`${target.href} redirected without a Location header.`);
+      if (hop >= MAX_REDIRECTS) {
+        throw new Error(`${input.url} redirected more than ${MAX_REDIRECTS} times.`);
+      }
+      // Resolved against the current URL so a relative Location works, then
+      // checked from scratch: a hop is a new destination, not a continuation.
+      target = await checkedUrl(new URL(location, target).href, addresses);
+      continue;
+    }
+
+    if (!response.ok) {
+      throw new Error(`${target.href} answered ${response.status} ${response.statusText}.`);
+    }
+
+    return {
+      bytes: await readCapped(response, input.maxBytes, target.href),
+      contentType: normalizeContentType(response.headers.get('content-type')),
+      filename: filenameFromDisposition(response.headers.get('content-disposition')),
+    };
+  }
+}
+
+/** Parse, require HTTPS, and refuse a host that resolves anywhere internal. */
+async function checkedUrl(candidate: string, addresses: AddressLookup): Promise<URL> {
+  let url: URL;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error(`"${candidate}" is not a URL.`);
+  }
+
+  if (url.protocol !== 'https:') {
+    throw new Error(
+      `Attachment URLs must be https — "${url.protocol}//" is not fetched. Stage the file instead if it is not reachable over HTTPS.`,
+    );
+  }
+
+  let resolved: readonly string[];
+  try {
+    resolved = await addresses(url.hostname);
+  } catch {
+    throw new Error(`${url.hostname} does not resolve.`);
+  }
+
+  if (resolved.length === 0) throw new Error(`${url.hostname} does not resolve.`);
+
+  for (const address of resolved) {
+    if (isBlocked(address)) {
+      throw new Error(
+        `${url.hostname} resolves to ${address}, which is a private, loopback, or link-local address. Refusing to fetch it.`,
+      );
+    }
+  }
+
+  return url;
+}
+
+/**
+ * Is this address one we must never connect to on a caller's behalf?
+ *
+ * Covers the ranges RFC 9728 §7.7 names, plus multicast and reserved space. The
+ * IPv4-mapped and NAT64 cases unwrap and re-check, because `::ffff:127.0.0.1` is
+ * loopback wearing a different spelling.
+ */
+export function isBlocked(address: string): boolean {
+  const version = isIP(address);
+  if (version === 4) return isBlockedV4(address);
+  if (version === 6) return isBlockedV6(address);
+  // Not an address at all. Treated as blocked because every caller here has
+  // already resolved a name, so an unparseable value means something upstream
+  // is wrong and connecting anyway is the worse failure.
+  return true;
+}
+
+function isBlockedV4(address: string): boolean {
+  const parts = address.split('.').map(Number);
+  const [a = 0, b = 0] = parts;
+
+  if (a === 0) return true; // 0.0.0.0/8 — "this host"
+  if (a === 10) return true; // private
+  if (a === 127) return true; // loopback
+  if (a === 169 && b === 254) return true; // link-local, incl. cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return true; // private
+  if (a === 192 && b === 168) return true; // private
+  if (a === 192 && b === 0) return true; // 192.0.0.0/24 protocol assignments
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
+  if (a === 198 && (b === 18 || b === 19)) return true; // benchmarking
+  if (a >= 224) return true; // multicast, reserved, broadcast
+
+  return false;
+}
+
+function isBlockedV6(address: string): boolean {
+  const bytes = ipv6Bytes(address);
+  if (!bytes) return true;
+
+  // IPv4-mapped (::ffff:0:0/96) and NAT64 (64:ff9b::/96) both carry a v4
+  // address in the last four bytes. Judge them as what they actually reach.
+  const mapped =
+    bytes.slice(0, 10).every((byte) => byte === 0) && bytes[10] === 0xff && bytes[11] === 0xff;
+  const nat64 =
+    bytes[0] === 0x00 &&
+    bytes[1] === 0x64 &&
+    bytes[2] === 0xff &&
+    bytes[3] === 0x9b &&
+    bytes.slice(4, 12).every((byte) => byte === 0);
+  if (mapped || nat64) {
+    return isBlockedV4(bytes.slice(12).join('.'));
+  }
+
+  if (bytes.every((byte) => byte === 0)) return true; // ::
+  if (bytes.slice(0, 15).every((byte) => byte === 0) && bytes[15] === 1) return true; // ::1
+  if ((bytes[0]! & 0xfe) === 0xfc) return true; // fc00::/7 unique local
+  if (bytes[0] === 0xfe && (bytes[1]! & 0xc0) === 0x80) return true; // fe80::/10 link-local
+  if (bytes[0] === 0xff) return true; // ff00::/8 multicast
+
+  return false;
+}
+
+/**
+ * Expand an IPv6 address to its sixteen bytes.
+ *
+ * Only ever called with a string `isIP` accepted, so the shape is already
+ * canonical — this handles `::` compression and a trailing dotted-quad, and
+ * returns null rather than guessing on anything else.
+ */
+function ipv6Bytes(address: string): number[] | null {
+  let text = address;
+
+  // A trailing IPv4 form (::ffff:127.0.0.1) becomes two more hextets.
+  const dotted = text.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const octets = dotted[1]!.split('.').map(Number);
+    if (octets.some((octet) => Number.isNaN(octet) || octet > 255)) return null;
+    const high = ((octets[0]! << 8) | octets[1]!).toString(16);
+    const low = ((octets[2]! << 8) | octets[3]!).toString(16);
+    text = `${text.slice(0, dotted.index)}${high}:${low}`;
+  }
+
+  const [head, tail, ...extra] = text.split('::');
+  if (extra.length > 0) return null;
+
+  const parse = (group: string | undefined): number[] => {
+    if (!group) return [];
+    return group.split(':').flatMap((hextet) => {
+      const value = Number.parseInt(hextet, 16);
+      return [(value >> 8) & 0xff, value & 0xff];
+    });
+  };
+
+  const front = parse(head);
+  const back = tail === undefined ? [] : parse(tail);
+  const gap = 16 - front.length - back.length;
+  if (gap < 0) return null;
+  if (tail === undefined && gap !== 0) return null;
+
+  return [...front, ...Array<number>(gap).fill(0), ...back];
+}
+
+/**
+ * Read the body, stopping at the cap.
+ *
+ * Streamed rather than `arrayBuffer()` because `Content-Length` is the server's
+ * claim about the server's own body — a hostile or broken one can understate it,
+ * and buffering first to measure second is how a size limit becomes a memory
+ * limit instead.
+ */
+async function readCapped(response: Response, maxBytes: number, href: string): Promise<Uint8Array> {
+  const declared = Number(response.headers.get('content-length') ?? Number.NaN);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new Error(`${href} is ${declared} bytes, over the ${maxBytes} byte limit.`);
+  }
+
+  if (!response.body) return new Uint8Array();
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        throw new Error(`${href} is larger than the ${maxBytes} byte limit.`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function normalizeContentType(header: string | null): string | null {
+  if (!header) return null;
+  const value = header.split(';')[0]?.trim().toLowerCase();
+  return value ? value : null;
+}
+
+/** `attachment; filename="report.pdf"`, and the RFC 5987 `filename*` form. */
+export function filenameFromDisposition(header: string | null): string | null {
+  if (!header) return null;
+
+  const extended = header.match(/filename\*\s*=\s*[^']*'[^']*'([^;]+)/i);
+  if (extended?.[1]) {
+    try {
+      return decodeURIComponent(extended[1].trim());
+    } catch {
+      /* fall through to the plain form */
+    }
+  }
+
+  const plain = header.match(/filename\s*=\s*("([^"]*)"|[^;]+)/i);
+  const value = plain?.[2] ?? plain?.[1];
+  return value ? value.trim() : null;
+}

package/src/connectivity/manifest/auth.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { credentialRef, identifier } from './primitives.ts';
+
+/**
+ * Credential types — how we prove who we are, orthogonal to how we connect.
+ *
+ * One folder per method under `../auth/`, and the union below is the complete
+ * list of what a manifest may declare today. Adding one is a schema member
+ * here, a folder there, and a branch in `../auth/resolve.ts` — see that
+ * directory's README, which names the ones not built yet.
+ */
+
+export const authNoneSchema = z.object({ kind: z.literal('none') });
+
+/**
+ * A client somebody else operates, so the operator does not have to register one.
+ *
+ * An installed application cannot hold a confidential client: whatever ships in
+ * the binary is readable by whoever runs it. That leaves exactly two honest
+ * arrangements, and this declares the second — the operator registers their own,
+ * or somebody runs one and performs the exchange on their behalf. The secret
+ * lives behind these endpoints and never reaches this machine.
+ *
+ * Vendor-free by construction. The URL is data a provider supplies, so nothing
+ * in this component learns whose client is behind it, or whose broker.
+ */
+export const authBrokerSchema = z.object({
+  /** Base URL. `<url>/config`, `<url>/exchange`, `<url>/refresh`. */
+  url: z.url(),
+  /** Who runs it, named in the sentence shown before consent. */
+  operator: z.string().min(1),
+  docs_url: z.url().optional(),
+});
+
+export type AuthBroker = z.infer<typeof authBrokerSchema>;
+
+export const authOAuthSchema = z.object({
+  kind: z.literal('oauth'),
+  /**
+   * `dynamic` — the authorization server offers Dynamic Client Registration, so
+   * we register ourselves and the operator does nothing at all (Notion, Linear).
+   *
+   * `manual` — the vendor requires a pre-registered client, so the operator
+   * supplies an id and secret (Google, including for Google's own MCP servers).
+   */
+  registration: z.enum(['dynamic', 'manual']).default('dynamic'),
+  /** Which `oauth_apps` entry holds the client, for `manual`. Shared across providers of a vendor. */
+  app: identifier.optional(),
+  /**
+   * Where to authorise when the profile declares no `oauth_apps` entry of its own.
+   *
+   * Additive rather than a third `registration` value, because the manifest is
+   * not what chooses. `registration: manual` stays true either way — the vendor
+   * does require a pre-registered client — and `app` still names the entry that
+   * overrides this. What decides is the profile: declaring the entry means "my
+   * own client", leaving it out means "the one the broker operates". A manifest
+   * that claimed one or the other would be wrong half the time.
+   */
+  broker: authBrokerSchema.optional(),
+  scopes: z.array(z.string()).default([]),
+  /**
+   * Usually discovered from the resource's metadata; set only to override.
+   *
+   * Required for an `http` connector, which has no MCP metadata document to
+   * discover from — a REST API is just a base URL, and where its authorization
+   * server lives is not something the API itself announces.
+   */
+  authorize_url: z.url().optional(),
+  token_url: z.url().optional(),
+  /**
+   * Extra parameters on the authorization request.
+   *
+   * Google needs `access_type=offline` and `prompt=consent`, without which it
+   * returns an access token and no refresh token — the connection then works
+   * for an hour and dies, which is a miserable thing to debug.
+   */
+  authorize_params: z.record(z.string(), z.string()).optional(),
+});
+
+export const authTokenSchema = z.object({
+  kind: z.enum(['bearer', 'api_key', 'header', 'basic']),
+  /** Header name for `header` / `api_key`. Defaults to `Authorization` / `X-API-Key`. */
+  header: z.string().optional(),
+  /** Send an `api_key` as a query parameter instead of a header. */
+  query: z.string().optional(),
+  /**
+   * The vendor group this credential belongs to, when several providers share
+   * one secret *per account*.
+   *
+   * Apple issues an app-specific password at account scope, so one password
+   * genuinely unlocks iCloud Mail, Calendar, and Contacts together — three
+   * providers, because they speak two protocols, but one thing to type. Setting
+   * `app: icloud` on all three moves the derived ref from `<provider>/<account>`
+   * to `icloud/<account>`.
+   *
+   * The same field on an *OAuth* block means something different and narrower:
+   * which `oauth_apps` entry holds the client. It deliberately does not move
+   * where tokens land, because Gmail and Drive share a Google client while
+   * holding separate tokens granted under different scopes.
+   */
+  app: identifier.optional(),
+  /**
+   * Omit for a per-account credential, which is the usual case and derives.
+   *
+   * Declaring one means the opposite: a single secret shared by *every* account
+   * of this provider — a service key, where the key is itself the identity.
+   */
+  credential_ref: credentialRef.optional(),
+});
+
+/**
+ * A pluggable strategy, for auth no declarative form should try to express.
+ *
+ * This is the *only* place per-vendor code is permitted outside `local`
+ * providers, and it exists because real APIs do things config cannot describe:
+ * bunq generates an RSA keypair, runs a three-step handshake, signs every
+ * request, and verifies the response signature. That earns ~150 lines of auth.
+ * It must never come to mean per-endpoint code again.
+ */
+export const authStrategySchema = z.object({
+  kind: z.literal('strategy'),
+  strategy: identifier,
+  credential_ref: credentialRef.optional(),
+  /** Strategy-specific settings, validated by the strategy itself. */
+  options: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const authSchema = z.discriminatedUnion('kind', [
+  authNoneSchema,
+  authOAuthSchema,
+  authTokenSchema,
+  authStrategySchema,
+]);
+
+export type AuthConfig = z.infer<typeof authSchema>;

package/src/connectivity/manifest/bundles.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { identifier } from './primitives.ts';
+
+/**
+ * A named group of capabilities.
+ *
+ * For `http` connectors these are derived from the HTTP method — GET and HEAD
+ * are `read`, mutating verbs are `write` — so a spec yields meaningful bundles
+ * with no curation. A manifest may still declare its own.
+ */
+export const bundleSchema = z.object({
+  name: identifier,
+  description: z.string().default(''),
+  oauth_scopes: z.array(z.string()).default([]),
+  /** Glob patterns over capability names. Empty means "everything not matched by another bundle". */
+  capabilities: z.array(z.string()).default([]),
+  default: z.boolean().default(false),
+});
+
+export const READ_BUNDLE = 'read';
+export const WRITE_BUNDLE = 'write';
+
+export type ScopeBundle = z.infer<typeof bundleSchema>;