@lanes-sh/link 0.3.2 → 0.4.1

package/src/cli/runtime/open.ts

@@ -79,6 +79,16 @@ export interface Runtime {
   readonly authenticator: BearerAuthenticator;
   /** Same factory the dispatcher uses, exposed for commands that probe upstream. */
   connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+  /**
+   * Same authorizer the dispatcher uses, for the same reason `connectorFor` is here.
+   *
+   * A command that probes upstream needs the credential on the request, and it
+   * must not learn how to put it there — that is one switch on the resolved
+   * shape (`connectivity/auth/authorize.ts`) and a second copy would be a
+   * second answer. `settleIdentity` is the caller: it asks a provider whose
+   * account was just authorised, over whatever method that provider declares.
+   */
+  authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
   /** A provider's manifest, so an omitted `credential_ref` can be derived from it. */
   manifestFor(providerId: string): ProviderManifest | undefined;
   close(): Promise<void>;
@@ -309,13 +319,14 @@ export async function openRuntime(
   // the *same instance* whichever side asks for it, or a held session is held
   // twice.
   const connectorFor = connectorFactory({ registry, credentials });
+  const authorizeRequest = requestAuthorizer(registry, credentials);
   let closed = false;
 
   const dispatcher = new Dispatcher({
     config,
     registry,
     connectorFor,
-    authorizeRequest: requestAuthorizer(registry, credentials),
+    authorizeRequest,
     policy,
     state,
     audit: auditSink,
@@ -345,6 +356,7 @@ export async function openRuntime(
       credentials,
     }),
     connectorFor,
+    authorizeRequest,
     manifestFor: (providerId: string) => registry.manifest(providerId),
     // Sessions first, then the state: a connector may still want to log out
     // cleanly, and LOGOUT is worth more than the microsecond it costs.

package/src/cli/runtime/registry.ts

@@ -2,6 +2,7 @@ import type { BlobStore } from '#stores/blobs';
 import type { ProviderDefinition } from '#connectivity';
 import { ConfigError } from '#profile';
 import { ProviderRegistry } from '#registry';
+import { RESERVED_BY_GRAMMAR } from '../commands/connect/custom/spec.ts';
 import { loadProfileProviders } from '#providers/custom/index.ts';
 import { loadProfileSkills, type LoadedSkill } from '#providers/skills/store.ts';
 import { exampleProvider } from '#providers/example/provider.ts';
@@ -144,6 +145,17 @@ export async function buildRegistryWithWorkspace(
         `${path}: provider "${manifest.id}" is already built in. Rename it, or remove the file to use the built-in.`,
       );
     }
+    // An id the CLI's own grammar has taken. `connect custom` refuses to create
+    // one, and this is the other half: a file written by hand — or before that
+    // command existed — would otherwise register cleanly, be unreachable
+    // forever, and say nothing about why.
+    if ((RESERVED_BY_GRAMMAR as readonly string[]).includes(manifest.id)) {
+      throw new ConfigError(
+        `${path}: provider "${manifest.id}" cannot be reached — "${manifest.id}" is the second word ` +
+          `of \`lanes link connect ${manifest.id}\`, which is the command that declares one. ` +
+          'Rename it.',
+      );
+    }
     registry.register(manifest, 'workspace');
   }
 

package/src/cli/selection.ts

@@ -10,6 +10,7 @@ import {
   targetsByName,
 } from '#profile';
 import type { Flags } from './argv.ts';
+import { CONNECT_CUSTOM_FLAGS } from './commands/connect/custom/spec.ts';
 import { nearest } from './nearest.ts';
 
 /**
@@ -110,6 +111,12 @@ export const SELECTION: Record<string, Requires> = {
   'identity list': 'profile',
 
   connect: 'profile+target',
+  // Its own row rather than an inheritance from `connect`. Both need the same
+  // two things, but the row is what makes `selectionKey` return the two-word
+  // key — and that is what keeps thirty declaration flags off
+  // `connect <provider>`, where a mistyped one would otherwise be accepted and
+  // ignored, which is the defect this whole file exists for.
+  'connect custom': 'profile+target',
   setup: 'profile+target',
   token: 'profile+target',
   audit: 'profile+target',
@@ -280,6 +287,11 @@ const UNIVERSAL = ['help', 'json', 'quiet'];
  * universal set plus whatever `SELECTION` says it must be told.
  */
 const ACCEPTS: Record<string, readonly string[]> = {
+  // Imported rather than written out. Thirty-odd entries here would take this
+  // file past the size budget for a data literal, and the command's own
+  // `spec.ts` already derives most of them from the per-kind field tables — so
+  // a flag added there cannot be forgotten here.
+  'connect custom': CONNECT_CUSTOM_FLAGS,
   // `own-client` is the older spelling of one of the routes `auth` names, kept
   // because it is in scripts and a year of documentation (ADR-038).
   connect: [

package/src/cli/usage.ts

@@ -26,6 +26,10 @@ ${style.bold('Everyday')}
   ${PROGRAM} connect <...> --replace    ask for the stored password or key again
   ${PROGRAM} connect <...> --auth <method>  pick how, where there is a choice
   ${PROGRAM} connect <...> --non-interactive [--json]
+  ${PROGRAM} connect custom <id> --connector <kind> --auth <method>
+                                 declare a service that is not built in, and connect it.
+                                 kinds: mcp, http, imap, dav, fs. Omit a value and it is
+                                 asked for; the manifest it writes is yours to edit
                                         answer nothing from a terminal: take every value
                                         from the credential store, or say what is missing
   ${PROGRAM} start [--only]             reconcile and serve every profile on one endpoint
@@ -137,7 +141,11 @@ ${style.bold('Other flags')}
                                  one this project operates (connect only)
   --auth <method>                which way in, where a provider offers two (connect
                                  only). "oauth" is the browser; the other is named
-                                 in the choice connect prints
+                                 in the choice connect prints. On connect custom it
+                                 names the credential type instead: none, bearer,
+                                 api-key, header, basic, oauth, strategy
+  --replace-manifest             rewrite a declaration that already exists and differs
+                                 (connect custom only — --replace is about the credential)
   --port <n>                     override the configured port (start only)
 
 Every command prints the profile and target it is acting on, before it acts.

package/src/connectivity/auth/README.md

@@ -15,7 +15,7 @@ transport asks when it has a token to send and no request to attach it to.
 | `basic/` | `basic` | `username:password`, RFC 7617's own encoding |
 | `oauth-authcode/` | `oauth` | a refresh token, exchanged on every use |
 | `oauth-jwt/` | `oauth` + `assertion` | a private key, signed into an assertion per exchange |
-| `strategy/` | `strategy` | the escape hatch — per-vendor code, none registered |
+| `strategy/` | `strategy` | the escape hatch — the seam only; the code is the provider's |
 
 ## Adding one
 
@@ -23,6 +23,13 @@ A folder, a member of `authSchema` in `../manifest/auth.ts`, and a case in
 `resolve.ts` (plus `authorize.ts` if it touches the request). Nothing else in
 the codebase learns about it — that is the point of the split.
 
+`strategy/` is the other shape, and holds no vendor code at all. It resolves the
+strategy a manifest names from the `ProviderDefinition` beside it and refuses
+when the two disagree; the implementation lives with its provider, because a
+folder of vendor code under `connectivity/` is precisely what the vendor-name
+rule in `architecture.test.ts` exists to prevent. `providers/bunq/strategy/` is
+the one there is. See [ADR-046](../../../docs/detailed/adr/046-an-auth-strategy-belongs-to-its-provider.md).
+
 `oauth-jwt/` is the exception that proves the shape rather than breaking it. It
 is not a `kind`, because it is a second way into a provider that already has
 one, so it hangs off the OAuth block as `auth.assertion` and is selected by the

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

@@ -1,10 +1,134 @@
+import type { AuthStrategy, AuthStrategyContext } from '../../connector.ts';
+import type { ProviderContext } from '../../context.ts';
+import type { ProviderDefinition } from '../../provider.ts';
+import type { ProviderManifest } from '../../manifest/index.ts';
+
 /**
  * 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.
+ * A strategy is the one place per-vendor code is permitted outside `local`
+ * providers, and it stays *auth* — a request in, an authorised request out.
+ * The moment one starts translating endpoints, the problem ADR-008 removed has
+ * come back.
+ *
+ * There is no global registry here, and that is deliberate. A strategy is not a
+ * plugin the runtime discovers; it is a property of the provider that needs it,
+ * so it travels on that provider's `ProviderDefinition` the same way an authored
+ * capability does. Two things follow, both of them the point:
+ *
+ *   - this component stays free of vendor names, which is the rule
+ *     `architecture.test.ts` holds over everything a request passes through
+ *   - adding one is still a folder under `providers/` and a line in its index,
+ *     rather than a folder here plus a registration somewhere else
+ */
+
+/**
+ * What `strategyFor` needs from the registry, and no more.
+ *
+ * Structural rather than the real `ProviderRegistry`, so this file states its
+ * dependency as two methods instead of importing a component to name a type.
+ */
+export interface StrategySource {
+  get(id: string): { readonly definition?: ProviderDefinition | undefined } | undefined;
+  list(): readonly { readonly definition?: ProviderDefinition | undefined }[];
+}
+
+/**
+ * The strategy a manifest declares.
+ *
+ * Its own definition first, which is the built-in case: `providers/bunq`
+ * carries the code for the manifest beside it, and the two must agree about
+ * which strategy that is. A manifest naming `strategy: acme` while its
+ * definition carries something else is a wiring mistake that would otherwise
+ * surface as a signature the vendor rejects — a long way from its cause.
+ *
+ * Then any other registered provider that supplies one by that name, which is
+ * the case a declaration-only manifest needs. A workspace YAML in
+ * `providers.d/` is parsed into a `ProviderManifest` and has no definition at
+ * all, so without this it could name a strategy and never reach it — and naming
+ * one is exactly what a manifest is for. It is also the only way to point a
+ * connection at a vendor's sandbox, since a built-in manifest's `options` are
+ * not the operator's to edit.
+ *
+ * Borrowing the *code* is not borrowing the *credential*: the ref still derives
+ * from the manifest's own id, so `bunq_sandbox` reads `bunq_sandbox/<id>` and
+ * cannot reach what `bunq` holds.
+ */
+export function strategyFor(
+  manifest: ProviderManifest,
+  source: StrategySource,
+): AuthStrategy {
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(`Provider "${manifest.id}" does not declare a strategy.`);
+  }
+
+  const named = manifest.auth.strategy;
+  const own = source.get(manifest.id)?.definition?.authStrategy;
+
+  if (own) {
+    if (own.id !== named) {
+      throw new Error(
+        `Provider "${manifest.id}" declares auth strategy "${named}" but carries "${own.id}".`,
+      );
+    }
+    return own;
+  }
+
+  const borrowed = source
+    .list()
+    .map((entry) => entry.definition?.authStrategy)
+    .find((strategy) => strategy?.id === named);
+
+  if (!borrowed) refuseStrategy(named);
+  return borrowed;
+}
+
+/**
+ * What a strategy is given, derived from what the provider is given.
+ *
+ * Narrower than a `ProviderContext` on purpose: the connection's own
+ * credentials read-only, its own scoped state, and its logger. Nothing else,
+ * and in particular no storage, no audit logger, and no signal — a strategy
+ * authenticates a request and has no business doing anything a provider does.
+ *
+ * `write` is the one part that varies, and the variation *is* the rule.
+ * Persisting a credential is a setup-time act, so `connect` passes a writer and
+ * the dispatch path does not. Per-request code then cannot store a credential
+ * because there is nothing on the object to store one with, rather than because
+ * somebody remembered not to.
+ *
+ * Takes the three fields it reads rather than a whole `ProviderContext`, so the
+ * two callers can be what they are: dispatch hands over the context it already
+ * built, and `connect` — which has no provider context, because the connection
+ * does not exist yet — assembles the same three from the runtime.
+ */
+export function strategyContextFrom(input: {
+  /** Dispatch hands over the `ProviderContext` it built; `connect` assembles the three itself. */
+  readonly source: Pick<ProviderContext, 'credentials' | 'state' | 'log'>;
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly profile: string;
+  readonly write?: ((ref: string, value: string) => Promise<void>) | undefined;
+}): AuthStrategyContext {
+  const { source, manifest, connectionId, profile, write } = input;
+
+  return {
+    manifest,
+    connectionId,
+    profile,
+    credentials: source.credentials,
+    state: source.state,
+    log: source.log,
+    options: manifest.auth.kind === 'strategy' ? (manifest.auth.options ?? {}) : {},
+    ...(write ? { write } : {}),
+  };
+}
+
+/**
+ * A manifest asked for a strategy nothing supplies.
+ *
+ * Fails loudly rather than sending an unauthenticated request, which would fail
+ * upstream with an error about the vendor rather than about the wiring.
  */
 export function refuseStrategy(strategy: string): never {
   throw new Error(

package/src/connectivity/connector.ts

@@ -159,6 +159,17 @@ export interface AuthStrategy {
 export interface AuthStrategyContext {
   readonly manifest: ProviderManifest;
   readonly connectionId: string;
+  /**
+   * Which profile this is acting for.
+   *
+   * Nothing about authenticating one request needs it. What needs it is any
+   * strategy that keeps something in process memory: one endpoint serves every
+   * profile in the workspace from one process, so `<provider>.<connection>` is
+   * not a unique key — two profiles each holding a bunq connection called
+   * `main` would share whatever it named. `state` and `credentials` are already
+   * scoped per profile and a cache in front of them must be too.
+   */
+  readonly profile: string;
   /** Read-only, scoped to this connection — the same boundary providers get. */
   readonly credentials: ProviderContext['credentials'];
   /**

package/src/connectivity/index.ts

@@ -48,7 +48,17 @@ export {
  * Everything else is a manifest.
  */
 export type { AuthRequirement, ProviderDefinition } from './provider.ts';
-export { defineLocalProvider, defineProviderWithCapabilities } from './provider.ts';
+export {
+  defineLocalProvider,
+  defineProviderWithCapabilities,
+  defineProviderWithStrategy,
+} from './provider.ts';
+
+/**
+ * The strategy seam. Vendor-free by construction: these three know that a
+ * strategy exists and never which one.
+ */
+export { refuseStrategy, strategyContextFrom, strategyFor } from './auth/strategy/index.ts';
 
 export type {
   ProviderManifest,

package/src/connectivity/manifest/auth.ts

@@ -164,6 +164,25 @@ export const authOAuthSchema = z.object({
    */
   authorize_url: z.url().optional(),
   token_url: z.url().optional(),
+  /**
+   * A loopback redirect to name to the vendor verbatim, for one that matches it
+   * exactly rather than by prefix.
+   *
+   * `connect` normally listens on a port the kernel picks, which works because
+   * most authorization servers accept any loopback port. One that pins the
+   * whole URL cannot: the port it was told in a console months ago is not the
+   * port this run happens to get, and the grant is refused with
+   * `redirect_uri_mismatch`.
+   *
+   * The full URL rather than a port, because the vendor's console decides the
+   * spelling — `localhost` and `127.0.0.1` are different strings to a matcher
+   * even when they are the same host — and the two must be identical.
+   *
+   * Mutually exclusive with `broker`, which answers the same question the other
+   * way: there the redirect is the broker's HTTPS origin and the loopback port
+   * travels in `state`.
+   */
+  redirect_uri: z.url().optional(),
   /**
    * Extra parameters on the authorization request.
    *

package/src/connectivity/manifest/connector.ts

@@ -56,6 +56,27 @@ export const httpConnectorSchema = z.object({
       exclude: z.array(z.string()).default([]),
     })
     .optional(),
+  /**
+   * Sent on every request this connector makes.
+   *
+   * The same field as `mcp`'s above and refused the same way for
+   * `Authorization` — but for the opposite reason. An mcp server chooses its
+   * own tool list and a header is the only way to ask it for less; a REST API
+   * asks for nothing, and this is for what the *vendor* requires of a client
+   * rather than what a caller wants from it.
+   *
+   * The case in hand is a `User-Agent`. Nothing else here sets one, so every
+   * install of this program looks identical to a host that rate-limits by
+   * client — and a service that asks callers to identify themselves throttles
+   * the default agent hardest, which reads as an outage rather than a refusal.
+   *
+   * Precedence is narrowest-wins: `accept` is a default this may override, a
+   * header parameter the operation itself declares overrides this, and
+   * `content-type` is derived from the document and overrides everything —
+   * a blanket header cannot silently change how one operation's body is
+   * encoded.
+   */
+  headers: z.record(z.string(), z.string()).optional(),
 });
 
 /**

package/src/connectivity/manifest/primitives.ts

@@ -16,5 +16,9 @@ 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',
+    // A placeholder rather than a real provider id. The example teaches the
+    // shape either way, and this file is inside the scope
+    // `architecture.test.ts` keeps free of vendor names — an error message that
+    // names one is exactly the "message that assumes a vendor" the rule is for.
+    'must be a credential reference like "acme/api_key", not a literal value',
   );

package/src/connectivity/manifest/provider.ts

@@ -225,6 +225,36 @@ export function defineProvider(input: unknown): ProviderManifest {
     );
   }
 
+  // Two answers to "where does the browser come back to", and a manifest
+  // naming both leaves it to whichever the flow reads first. A broker's
+  // redirect is its own HTTPS origin, with the loopback port carried in
+  // `state`; a fixed redirect is this machine, named exactly. Neither is wrong,
+  // but they cannot both be in force.
+  if (manifest.auth.kind === 'oauth' && manifest.auth.broker && manifest.auth.redirect_uri) {
+    throw new Error(
+      `Provider "${manifest.id}": auth may declare "broker" or "redirect_uri", not both — a brokered flow redirects to the broker and carries the loopback port in state, so a fixed redirect would never be used.`,
+    );
+  }
+
+  // Connector headers are for what the *server* offers as configuration; the
+  // credential is the auth block's, and a manifest setting both would have one
+  // quietly overwrite the other depending on which the transport merged last.
+  //
+  // Checked for every connector that has the field rather than for `mcp` alone.
+  // It was written when `mcp` was the only one, and the reasoning never had
+  // anything to do with which transport carried the header — an `http`
+  // connector naming `Authorization` collides with `auth` in exactly the same
+  // way, and would have validated cleanly.
+  const connectorHeaders =
+    'headers' in manifest.connector ? (manifest.connector.headers ?? {}) : {};
+  for (const name of Object.keys(connectorHeaders)) {
+    if (name.toLowerCase() === 'authorization') {
+      throw new Error(
+        `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
+      );
+    }
+  }
+
   if (manifest.connector.kind === 'mcp') {
     const auth = manifest.auth;
 
@@ -250,18 +280,6 @@ export function defineProvider(input: unknown): ProviderManifest {
         `Provider "${manifest.id}": an mcp connector always sends its token as "Authorization: Bearer", so auth.header ("${auth.header}") cannot be honoured. Remove it, or reach this service with an http connector.`,
       );
     }
-
-    // The third spelling of the same collision. Connector headers are for what
-    // the *server* offers as configuration; the credential is the auth block's,
-    // and a manifest setting both would have one quietly overwrite the other
-    // depending on which the transport merged last.
-    for (const name of Object.keys(manifest.connector.headers ?? {})) {
-      if (name.toLowerCase() === 'authorization') {
-        throw new Error(
-          `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
-        );
-      }
-    }
   }
 
   const names = new Set<string>();

package/src/connectivity/provider.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { SecretRef } from '#secrets';
 import type { Capability } from './capability.ts';
+import type { AuthStrategy } from './connector.ts';
 import type { ProviderContext } from './context.ts';
 import { bundleSchema, defineProvider, type ProviderManifest } from './manifest/index.ts';
 
@@ -32,6 +33,16 @@ export interface ProviderDefinition<
 
   readonly capabilities: readonly Capability[];
 
+  /**
+   * Pluggable auth, for a vendor whose handshake no manifest field can describe.
+   *
+   * Carried here rather than in a registry the runtime searches, because a
+   * strategy belongs to exactly one provider and nothing else may use it. The
+   * manifest declares *that* there is one and names it; this is the code, and
+   * `strategyFor` checks the two agree.
+   */
+  readonly authStrategy?: AuthStrategy;
+
   /**
    * Which credential refs a connection may read. Core turns this into the
    * allowlist behind `ProviderContext.credentials`, so a provider cannot reach
@@ -161,3 +172,47 @@ export function defineProviderWithCapabilities(input: {
     capabilities: input.capabilities,
   };
 }
+
+/**
+ * A manifest-based provider whose authentication is code rather than a field.
+ *
+ * The sibling of `defineProviderWithCapabilities`, and rarer. That one exists
+ * where a vendor's API can do something its *document* cannot express; this one
+ * where a vendor's **handshake** can. Everything else about the provider stays
+ * declared — the connector kind, the operations, the redaction — and the
+ * strategy only ever sees a request on its way out and a response on its way
+ * back.
+ *
+ * ADR-008 puts a number on how much this is allowed to be: roughly 150 lines,
+ * for auth, once. A strategy that grows a second job is the 612-line problem
+ * returning by a different door.
+ */
+export function defineProviderWithStrategy(input: {
+  readonly manifest: ProviderManifest;
+  readonly strategy: AuthStrategy;
+  readonly capabilities?: readonly Capability[];
+}): ProviderDefinition {
+  const { manifest, strategy } = input;
+
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(
+      `Provider "${manifest.id}" carries an auth strategy but declares auth.kind "${manifest.auth.kind}". Declare { kind: 'strategy', strategy: '${strategy.id}' }.`,
+    );
+  }
+
+  if (manifest.auth.strategy !== strategy.id) {
+    throw new Error(
+      `Provider "${manifest.id}" declares auth strategy "${manifest.auth.strategy}" but carries "${strategy.id}".`,
+    );
+  }
+
+  return {
+    manifest,
+    // Permissive for the same reason `defineProviderWithCapabilities` is: a
+    // manifest provider's connection is already described by its manifest.
+    configSchema: z.unknown(),
+    connectionSchema: z.unknown(),
+    capabilities: input.capabilities ?? [],
+    authStrategy: strategy,
+  };
+}

package/src/connectivity/transports/factory.ts

@@ -180,6 +180,7 @@ function build(
         ...(manifest.connector.operations?.exclude?.length
           ? { exclude: manifest.connector.operations.exclude }
           : {}),
+        ...(manifest.connector.headers ? { headers: manifest.connector.headers } : {}),
       });
   }
 }

package/src/connectivity/transports/http/index.ts

@@ -26,9 +26,70 @@ export interface HttpConnectorOptions {
   readonly openapi: string;
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
+  /** Sent on every request. Never `Authorization` — the manifest refuses it. */
+  readonly headers?: Readonly<Record<string, string>>;
   readonly fetch?: typeof globalThis.fetch;
 }
 
+/**
+ * The one body encoding that is not JSON often enough to be worth knowing about.
+ *
+ * A form-encoded write is not a legacy curiosity: it is what a large share of
+ * APIs that predate JSON request bodies still require, and one of them refusing
+ * `application/json` is not a negotiation — the request fails outright, with an
+ * error about the parameters rather than about the encoding.
+ */
+const FORM_ENCODED = 'application/x-www-form-urlencoded';
+
+/**
+ * What the *document* says the body is, rather than what we would prefer.
+ *
+ * `mcp-from-openapi` records the declared media type on each body entry of the
+ * mapper, so this needs nothing threaded through `target` — the mapper is
+ * already cached there, which is what lets a cold instance encode correctly
+ * without re-reading the spec.
+ *
+ * JSON is the default because an operation with no declared request body has no
+ * media type to read, and because it is what this connector always sent.
+ */
+function bodyContentType(mapper: readonly ParameterMapper[]): string {
+  for (const entry of mapper) {
+    if (entry.type !== 'body') continue;
+    const declared = entry.serialization?.contentType;
+    if (declared) return declared;
+  }
+
+  return 'application/json';
+}
+
+/**
+ * Arrays repeat rather than join, for the reason the query string does above.
+ *
+ * A nested object is JSON inside the field, which is the only thing a
+ * form-encoded body can do with one — there is no standard spelling of nesting
+ * here, and every API that accepts one accepts it as a string.
+ */
+function encodeBody(body: Readonly<Record<string, unknown>>, contentType: string): string {
+  if (!contentType.startsWith(FORM_ENCODED)) return JSON.stringify(body);
+
+  const form = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      for (const element of value) {
+        if (element !== undefined && element !== null) form.append(key, String(element));
+      }
+      continue;
+    }
+
+    form.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+
+  return form.toString();
+}
+
 /**
  * `*` matches any run of characters; anything else is literal.
  *
@@ -148,6 +209,12 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
 
       const url = new URL(options.baseUrl.replace(/\/$/, '') + buildPath(template, args, mapper));
       const headers = new Headers({ accept: 'application/json' });
+
+      // After `accept`, which is a default worth overriding, and before the
+      // operation's own header parameters, which are narrower than a header
+      // declared once for the whole connector.
+      for (const [key, value] of Object.entries(options.headers ?? {})) headers.set(key, value);
+
       const body = collect(args, mapper, 'body');
 
       for (const [key, value] of Object.entries(collect(args, mapper, 'query'))) {
@@ -174,7 +241,11 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
       }
 
       const hasBody = Object.keys(body).length > 0;
-      if (hasBody) headers.set('content-type', 'application/json');
+      const contentType = bodyContentType(mapper);
+      // Last, so it beats a connector-wide header. Which encoding an operation
+      // uses is the document's to state, and a blanket `content-type` that
+      // silently changed it would be a bug nobody could see from the manifest.
+      if (hasBody) headers.set('content-type', contentType);
 
       // Auth is attached by core, from the manifest's auth kind or its strategy.
       // A connector never sees a raw credential.
@@ -182,7 +253,7 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
         new Request(url.href, {
           method,
           headers,
-          ...(hasBody ? { body: JSON.stringify(body) } : {}),
+          ...(hasBody ? { body: encodeBody(body, contentType) } : {}),
           signal: context.provider.signal,
         }),
       );