@lanes-sh/link 0.3.2 → 0.4.0

package/src/cli/commands/connect/settle.ts

@@ -27,6 +27,7 @@ export async function settleIdentity(input: {
     credentials: SecretStore;
     registry: { manifest(id: string): ProviderManifest | undefined };
     connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+    authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
   };
   prompter?: Prompter;
 }): Promise<{ connectionId: string; account: string }> {
@@ -51,8 +52,24 @@ export async function settleIdentity(input: {
   if (!account) {
     const token = () => bearerTokenAsStored(manifest, provisionalId, runtime.credentials);
 
+    // Only where `accessToken` cannot answer: `requestAuthorizer` goes through
+    // `credentialResolver`, which may *refresh* an OAuth token, and
+    // `bearerTokenAsStored` is deliberately the connect-time variant that does
+    // not. Leaving oauth and bearer on the token keeps refresh behaviour
+    // exactly as it was; these three had no working path at all.
+    const carriesItsOwnHeader =
+      manifest.auth.kind === 'api_key' ||
+      manifest.auth.kind === 'header' ||
+      manifest.auth.kind === 'basic';
+
     account = await resolveAccount(manifest, {
       accessToken: token,
+      ...(carriesItsOwnHeader
+        ? {
+            authorize: (request: Request) =>
+              runtime.authorizeRequest(manifest.id, provisionalId, request),
+          }
+        : {}),
       // A protocol that authenticates by username has nothing to GET and no
       // tool to call — it knows, once the server has accepted the login.
       identify: async () =>

package/src/cli/commands/connect/setup.ts

@@ -145,7 +145,15 @@ export async function ensureStaticCredential(input: {
   const { manifest, connectionId, credentials, replace, provisional } = input;
   const prompter = input.prompter ?? terminalPrompter;
   const auth = manifest.auth;
-  if (auth.kind === 'none' || auth.kind === 'oauth' || auth.kind === 'strategy') return;
+  // `strategy` used to be excluded here, from when no strategy existed and the
+  // kind was unreachable. It is exactly the wrong exclusion: a strategy
+  // provider's credential is *more* of a pasted value than most — bunq's API
+  // key is the input its handshake runs on — and skipping the prompt left
+  // `lanes link connect bunq` storing nothing and then failing inside the
+  // handshake with "no API key was stored", on the interactive path the setup
+  // documentation describes. Everything below is generic: the ref derives, the
+  // prompts come from the manifest.
+  if (auth.kind === 'none' || auth.kind === 'oauth') return;
 
   const ref = credentialRefForConnection(manifest, connectionId)!;
   const stored = await credentials.has(ref);

package/src/cli/commands/connect/strategy.ts

@@ -0,0 +1,87 @@
+import { credentialRefForConnection, strategyContextFrom, strategyFor } from '#connectivity';
+import type { ProviderManifest } from '#connectivity';
+import { createScopedStore, scopeNamespace } from '#dispatch';
+import { scopeSecrets } from '#secrets';
+import type { SecretStore } from '#secrets';
+import type { RuntimeState } from '#stores/state';
+import type { ProviderRegistry } from '#registry';
+import { progress, style } from '../../output.ts';
+
+/**
+ * The handshake a strategy provider needs before it can be called at all.
+ *
+ * Ordinary providers finish authenticating the moment the operator pastes
+ * something: the value *is* the credential. A strategy provider has only half
+ * of one at that point — bunq's API key is the input to an installation, not a
+ * token — so this runs the vendor's own setup between storing what was pasted
+ * and asking whose account it is.
+ *
+ * **Why it sits where it does in `connect`.** After the credential is stored,
+ * because the handshake's input is what was pasted. Before identity is settled
+ * and anything is written to the config, because a key the vendor rejects
+ * should fail here — with the vendor's own message — rather than leaving a
+ * connection row describing an account that cannot be reached. It runs under
+ * the *provisional* connection id for the same reason every other step does:
+ * the real one is not known yet, and `connect` moves the credential when it is.
+ *
+ * Here rather than in `index.ts` because that file is at its size budget, and
+ * because this is one self-contained step: everything it needs is a manifest
+ * and a runtime, and everything it produces is in the credential store.
+ */
+export async function runStrategySetup(
+  manifest: ProviderManifest,
+  /** The provisional id. `connect` renames the connection afterwards and the credential follows. */
+  connectionId: string,
+  /** Structurally the CLI `Runtime`, named as the parts this actually reaches. */
+  runtime: {
+    readonly registry: ProviderRegistry;
+    readonly credentials: SecretStore;
+    readonly state: RuntimeState;
+    readonly resolution: { readonly profile: string };
+  },
+): Promise<void> {
+  const { registry, credentials, state } = runtime;
+  const profile = runtime.resolution.profile;
+  if (manifest.auth.kind !== 'strategy') return;
+
+  const strategy = strategyFor(manifest, registry);
+  if (!strategy.setup) return;
+
+  // The one ref this connection may read, which is also the one the pasted
+  // value landed in and the one the handshake will rewrite.
+  const ref = credentialRefForConnection(manifest, connectionId)!;
+
+  const context = strategyContextFrom({
+    source: {
+      credentials: scopeSecrets(credentials, [ref]),
+      state: createScopedStore(state, scopeNamespace(manifest.id, connectionId)),
+      log: {
+        debug: () => {},
+        info: (message) => progress(style.dim(`  ${message}`)),
+        warn: (message) => progress(style.dim(`  ${message}`)),
+        error: (message) => progress(style.dim(`  ${message}`)),
+      },
+    },
+    manifest,
+    connectionId,
+    profile,
+    // Writable *only* here — the dispatch path passes nothing, so a per-request
+    // handshake cannot persist anything.
+    //
+    // Scoped to the same single ref the reads are. Handing over the raw store
+    // would leave the write side of this boundary open while the read side is
+    // shut, which is the asymmetry that makes a boundary decorative: a strategy
+    // could not *read* `google/main` and could quietly overwrite it.
+    write: async (reference, value) => {
+      if (reference !== ref) {
+        throw new Error(
+          `The ${manifest.name} strategy tried to write ${reference}, which is not its connection's credential (${ref}).`,
+        );
+      }
+      await credentials.set(reference, value);
+    },
+  });
+
+  progress(style.dim(`  Registering this device with ${manifest.name}…`));
+  await strategy.setup(context);
+}

package/src/cli/commands/connect/unknown.ts

@@ -0,0 +1,41 @@
+import { layout } from '#profile';
+import type { ProviderRegistry } from '#registry';
+import { PROGRAM } from '../../usage.ts';
+
+/**
+ * What to say when a name resolves to no provider.
+ *
+ * The one message that has to teach something, because a misspelling and a
+ * service nobody has integrated arrive here identically and want opposite
+ * answers. So it prints both lists — what is shipped, and what this profile has
+ * added — and then the command that adds another.
+ *
+ * It named `<root>/providers/` for a long time, which is not where manifests
+ * live and never was. The path comes from `layout` now, like every other
+ * profile-owned path, and the "add your own" line is printed whether or not the
+ * operator already has one: showing it only to somebody with none meant hiding
+ * it from everybody except the one person who could not yet know it existed.
+ */
+export function unknownProvider(input: {
+  readonly providerId: string;
+  readonly registry: ProviderRegistry;
+  readonly workspaceRoot: string;
+  readonly profile: string;
+  readonly target: string;
+}): Error {
+  const available = input.registry.list();
+  const builtin = available.filter((c) => c.origin === 'builtin').map((c) => c.manifest.id);
+  const yours = available.filter((c) => c.origin === 'workspace').map((c) => c.manifest.id);
+
+  const selection = `--profile ${input.profile} --target ${input.target}`;
+  const directory = `${input.workspaceRoot}/${layout.providers(input.profile)}`;
+
+  return new Error(
+    `Unknown provider "${input.providerId}".\n` +
+      `  built in: ${builtin.join(', ')}\n` +
+      (yours.length > 0 ? `  yours:    ${yours.join(', ')}\n` : '') +
+      `  add your own: ${PROGRAM} connect custom ${input.providerId}` +
+      ` --connector <kind> --auth <method> ${selection}\n` +
+      `                or a manifest in ${directory}\n`,
+  );
+}

package/src/cli/identity.ts

@@ -29,9 +29,29 @@ export function pluck(value: unknown, path: string): string | null {
   return typeof current === 'string' && current.length > 0 ? current : null;
 }
 
+/** The header an OAuth or bearer provider's probe carries. */
+async function bearerHeaders(probe: IdentityProbe): Promise<RequestInit> {
+  const token = await probe.accessToken();
+  return { headers: token ? { authorization: `Bearer ${token}` } : {} };
+}
+
 export interface IdentityProbe {
   /** A valid upstream access token, if the provider authenticates. */
   readonly accessToken: () => Promise<string | null>;
+  /**
+   * Put this connection's credential on a request, whatever method it is.
+   *
+   * Supplied where `accessToken` cannot answer. A stored `api_key`, `header` or
+   * `basic` credential is not a bearer token and `bearerToken` throws for all
+   * three — under a comment calling the branch unreachable, which it is on an
+   * mcp connector and is not on an http one. The throw was caught by the
+   * catch-all below, so an `identity: { kind: http }` block on the commonest
+   * custom shape there is — a REST API behind an API key — never worked and
+   * never said so: the operator was asked to name the account by hand on every
+   * reconnect, and a different answer each time is a new row rather than a
+   * repair.
+   */
+  readonly authorize?: (request: Request) => Promise<Request>;
   /** Call a capability on the upstream MCP server. */
   readonly callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
   /** Ask the connector, for a protocol whose identity is not a URL away. */
@@ -52,11 +72,15 @@ export async function resolveAccount(
     }
 
     if (identity.kind === 'http') {
-      const token = await probe.accessToken();
-      const request = probe.fetch ?? globalThis.fetch;
-      const response = await request(identity.url, {
-        headers: token ? { authorization: `Bearer ${token}` } : {},
-      });
+      const send = probe.fetch ?? globalThis.fetch;
+
+      // `authorize` where the caller supplied one, because it is the same
+      // switch the dispatch path uses and knows every method. The token is the
+      // fallback rather than the other way round only because the OAuth
+      // providers reached here first; both end at the same header for them.
+      const response = probe.authorize
+        ? await send(await probe.authorize(new Request(identity.url)))
+        : await send(identity.url, await bearerHeaders(probe));
       if (!response.ok) return null;
 
       const body = await response.json();

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { connect } from './commands/connect/index.ts';
+import { connectCustom } from './commands/connect/custom/index.ts';
 import {
   attachFile,
   auditTail,
@@ -29,7 +30,7 @@ import { secretsList, secretsPush, secretsSet } from './commands/secrets.ts';
 import { knowledgeShow, knowledgeUse } from './commands/knowledge.ts';
 import { dispatchOwner } from './dispatch-owner.ts';
 import { update } from './commands/update.ts';
-import { all, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import { all, customFlags, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
 import { assertKnownFlags, requireSelection } from './selection.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
@@ -75,18 +76,41 @@ export async function run(argv: readonly string[]): Promise<void> {
 
   switch (first) {
     case 'connect':
-      if (!second) throw new Error(`Usage: ${PROGRAM} connect <provider>`);
-      return connect(second, {
-        ...global,
-        id: text(flags, 'id'),
-        displayName: text(flags, 'display-name'),
-        replace: flags['replace'] === true,
-        nonInteractive: flags['non-interactive'] === true,
-        acceptBroadScopes: flags['accept-broad-scopes'] === true,
-        ownClient: flags['own-client'] === true,
-        auth: text(flags, 'auth'),
-        json,
-      });
+      // A nested switch rather than an `if`, so `selection.test.ts` sees
+      // `connect custom` when it reads this file for `case` labels: it matches
+      // on eight-space indentation, and a command invisible to that check is a
+      // command that can default quietly.
+      switch (second) {
+        case 'custom':
+          return connectCustom(rest[0], {
+            ...global,
+            ...customFlags(flags, argv),
+            id: text(flags, 'id'),
+            displayName: text(flags, 'display-name'),
+            replace: flags['replace'] === true,
+            nonInteractive: flags['non-interactive'] === true,
+            acceptBroadScopes: flags['accept-broad-scopes'] === true,
+            json,
+          });
+
+        // Not a `case` label, so it adds no row to `SELECTION`: there is no
+        // command here to classify, only a usage error.
+        case undefined:
+          throw new Error(`Usage: ${PROGRAM} connect <provider>`);
+
+        default:
+          return connect(second, {
+            ...global,
+            id: text(flags, 'id'),
+            displayName: text(flags, 'display-name'),
+            replace: flags['replace'] === true,
+            nonInteractive: flags['non-interactive'] === true,
+            acceptBroadScopes: flags['accept-broad-scopes'] === true,
+            ownClient: flags['own-client'] === true,
+            auth: text(flags, 'auth'),
+            json,
+          });
+      }
 
     case 'setup':
       if (second !== 'plan' && second !== undefined) {

package/src/cli/oauth.ts

@@ -66,6 +66,27 @@ export interface OAuthFlowOptions {
    * on the way back. What changes is only the address the vendor is told.
    */
   readonly relayRedirect?: string;
+  /**
+   * A redirect this machine listens on, named to the vendor exactly as written.
+   *
+   * The third answer to "where does the browser come back to", and the one the
+   * comment above did not anticipate. `relayRedirect` exists for a vendor that
+   * will take no loopback address at all; this is for a vendor that takes one
+   * happily but matches it *exactly*, port included — so the kernel-chosen port
+   * below can never match a URL registered in a console months earlier.
+   *
+   * That is not a rare shape. It is the reason `providers/github/index.ts`
+   * gives for using a pasted token rather than OAuth: "an OAuth App matches its
+   * callback URL exactly, including the port, and `connect` listens on a port
+   * the kernel picks."
+   *
+   * The whole URL rather than just a port, because the two must be identical
+   * strings and only one of them is ours to choose. A console that accepts
+   * `localhost` but not `127.0.0.1` — or insists on a trailing path — decides
+   * the spelling, and a manifest that could only name a number would have to
+   * guess the rest right.
+   */
+  readonly fixedRedirect?: string;
   /** What the completion page names as connected. A provider's display name. */
   readonly connectionLabel?: string;
   /** How long to wait for the operator to finish in the browser. */
@@ -130,48 +151,80 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
     rejectCode = reject;
   });
 
-  const server = Bun.serve({
-    hostname: '127.0.0.1',
-    port: 0, // let the OS choose; nothing outside this machine names this port
-    fetch(request) {
-      const url = new URL(request.url);
-      if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
-
-      const error = url.searchParams.get('error');
-      if (error) {
-        rejectCode(
-          new OAuthError(
-            error === 'access_denied'
-              ? 'Authorization was declined in the browser.'
-              : `Authorization failed: ${error}`,
-          ),
-        );
-        return failedPage('You can close this tab.');
-      }
+  // A fixed redirect is only fixed if we listen where it says. Parsed rather
+  // than configured separately so the two cannot disagree: the port the vendor
+  // was told is by construction the port this binds.
+  const fixed = options.fixedRedirect ? new URL(options.fixedRedirect) : undefined;
+  const fixedPort = fixed ? Number(fixed.port) : undefined;
 
-      const returnedState = url.searchParams.get('state');
-      if (!returnedState || !stateMatches(state, returnedState)) {
-        // A mismatched state means this callback did not come from the
-        // request we started. Refuse it rather than redeeming whatever code
-        // it carries.
-        rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
-        return failedPage('Unexpected callback.');
-      }
+  if (fixed && !fixedPort) {
+    throw new OAuthError(
+      `The redirect "${options.fixedRedirect}" names no port, so there is nothing for this machine to listen on. Register a redirect with an explicit port, such as http://127.0.0.1:8765/callback.`,
+    );
+  }
 
-      const code = url.searchParams.get('code');
-      if (!code) {
-        rejectCode(new OAuthError('The callback carried no authorization code.'));
-        return failedPage('No code returned.');
-      }
+  // Bun.serve throws synchronously when a port is taken. With a kernel-chosen
+  // port that cannot happen; with a fixed one it is the ordinary failure — a
+  // previous run still holding the socket, or another program on the port the
+  // vendor was told about. The raw EADDRINUSE names neither the provider nor
+  // the redirect, so it reads as a crash rather than as something to fix.
+  const server = ((): ReturnType<typeof Bun.serve> => {
+    try {
+    return Bun.serve({
+      hostname: '127.0.0.1',
+      // Zero lets the OS choose, which is right whenever nothing outside this
+      // machine names the port. A fixed redirect is exactly the case where
+      // something does.
+      port: fixedPort ?? 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
 
-      resolveCode(code);
-      return connectedPage(options.connectionLabel);
-    },
-  });
+        const error = url.searchParams.get('error');
+        if (error) {
+          rejectCode(
+            new OAuthError(
+              error === 'access_denied'
+                ? 'Authorization was declined in the browser.'
+                : `Authorization failed: ${error}`,
+            ),
+          );
+          return failedPage('You can close this tab.');
+        }
+
+        const returnedState = url.searchParams.get('state');
+        if (!returnedState || !stateMatches(state, returnedState)) {
+          // A mismatched state means this callback did not come from the
+          // request we started. Refuse it rather than redeeming whatever code
+          // it carries.
+          rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
+          return failedPage('Unexpected callback.');
+        }
+
+        const code = url.searchParams.get('code');
+        if (!code) {
+          rejectCode(new OAuthError('The callback carried no authorization code.'));
+          return failedPage('No code returned.');
+        }
+
+        resolveCode(code);
+        return connectedPage(options.connectionLabel);
+      },
+    });
+    } catch (cause) {
+      if (fixedPort) {
+        throw new OAuthError(
+          `Port ${fixedPort} is already in use, so the callback for this connection cannot be served. The redirect registered with the provider names that port exactly, so it cannot simply be moved — free the port and try again.`,
+        );
+      }
+      throw cause;
+    }
+  })();
 
   // Where the vendor is told to send the browser. The relay bounces it back
   // here; without one it comes here directly, which is every other provider.
-  const redirectUri = options.relayRedirect ?? `http://127.0.0.1:${server.port}/callback`;
+  const redirectUri =
+    options.relayRedirect ?? options.fixedRedirect ?? `http://127.0.0.1:${server.port}/callback`;
 
   /**
    * The CSRF binding, and — behind a relay — the only way home.

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