@lanes-sh/link 0.2.1 → 0.3.0

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

@@ -0,0 +1,187 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { ASSERTION_GRANT, parseAssertionKey } from '#connectivity/auth/index.ts';
+import { credentialRefForConnection, type AuthAssertion, type ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { ok, progress, style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { askForSetup, printSetup } from './setup.ts';
+
+/**
+ * The counterpart to `authorise.ts`, for a provider authenticated by a key.
+ *
+ * The same conversation, minus the browser: show the console work, take what it
+ * produced, put it in the store. What differs is that there are two halves and
+ * they have different lifetimes — the key is one file covering every provider
+ * of a vendor, and the account it acts as is per connection. So the key is
+ * asked for once per profile and the subject once per account, and re-running
+ * `connect` for a second provider asks for neither.
+ */
+
+/**
+ * Take a path, or the file's contents.
+ *
+ * A key arrives as a downloaded file, and a downloaded file is a path — asking
+ * someone to open it and paste several hundred characters of PEM into a
+ * terminal is asking for a truncated key and an error two steps later. Pasting
+ * still works for anyone who would rather, which is why this looks at the shape
+ * of the answer rather than at a flag.
+ *
+ * What is *stored* is always the contents. A path is a fact about one machine
+ * and this credential outlives it: the same profile is read by a deployed
+ * revision that has no such file, and a store holding a path would fail there
+ * with an error about the filesystem rather than about the credential.
+ */
+async function contentsOf(answer: string): Promise<string> {
+  if (answer.startsWith('{')) return answer;
+
+  const expanded = answer.startsWith('~/') ? resolve(homedir(), answer.slice(2)) : answer;
+  const path = isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded);
+
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    throw new Error(
+      `No file at ${path}. Give the path to the key the console downloaded, or paste its contents.`,
+    );
+  }
+}
+
+/**
+ * Ensure the profile holds the key, and this connection holds a pointer to it.
+ *
+ * Idempotent on the key for the same reason `ensureStaticCredential` is: seven
+ * providers share one file, and the second `connect` must find it already there
+ * and say so rather than asking again. The subject is not idempotent in the
+ * same way — it is per connection, and every connection is a first one.
+ */
+export async function authoriseWithKey(input: {
+  readonly manifest: ProviderManifest;
+  readonly assertion: AuthAssertion;
+  readonly connectionId: string;
+  readonly credentials: SecretStore;
+  readonly changes: string[];
+  /** The operator asked to be asked again — a rotated key, or the wrong account. */
+  readonly replace: boolean;
+  readonly prompter?: Prompter;
+}): Promise<void> {
+  const { manifest, assertion, connectionId, credentials, changes, replace } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+
+  const keyPrompt = assertion.setup.prompts.find((prompt) => prompt.scope === 'shared');
+  if (!keyPrompt) {
+    throw new Error(
+      `Provider "${manifest.id}" declares auth.assertion with no shared prompt, so there is no key to ask for.`,
+    );
+  }
+
+  const stored = await credentials.has(assertion.key_ref);
+
+  // `stored && !replace`, and deliberately not `reuseStoredCredential` — which
+  // also asks whether the connection id is still provisional. That question is
+  // right for a per-connection credential, where a provisional id means an
+  // earlier connect stored something no server ever accepted. It is wrong here:
+  // this key is shared across the whole profile, so a *first* connect of a
+  // second provider is provisional by definition while the key it finds was
+  // stored deliberately and may already be in use. Asking again there made a
+  // stored key unusable — the preflight said it had everything it needed, and
+  // the run that followed immediately asked for it.
+  if (stored && !replace) {
+    // The walkthrough still prints. The key is shared and already held, but the
+    // *sharing* is per resource and per product: whoever connects Sheets after
+    // Drive has a key that works and a spreadsheet nobody has shared with it
+    // yet, and that failure looks exactly like a broken credential.
+    printSetup(
+      manifest,
+      `The key is already stored at ${assertion.key_ref}, so it is not asked for again — but what ` +
+        'it can reach is granted per resource, and this is the first connection of this one.',
+      assertion.setup,
+    );
+    progress(ok(`key already stored (${assertion.key_ref})`));
+    // Named because this is the only way past a key that is stored and wrong,
+    // and a well-formed key for the wrong project is refused by the token
+    // endpoint rather than here.
+    progress(style.dim(`  To replace it: lanes link connect ${manifest.id} --replace`));
+  } else {
+    if (stored) {
+      progress(
+        style.dim(
+          `Replacing ${assertion.key_ref} — what is stored is overwritten only once you have entered a new one.`,
+        ),
+      );
+    }
+
+    const answers = await askForSetup(
+      manifest,
+      [keyPrompt],
+      `Stored at ${assertion.key_ref}, in the credential store — never in config.`,
+      prompter,
+      assertion.setup,
+    );
+
+    const contents = await contentsOf(answers.get(keyPrompt.key)!);
+
+    // Parsed before it is written, so the wrong file is caught here rather than
+    // at the token endpoint. The two candidates live on adjacent pages of the
+    // same console and `parseAssertionKey` knows how to tell them apart.
+    const key = parseAssertionKey(contents, assertion.key_ref);
+
+    await credentials.set(assertion.key_ref, contents);
+    changes.push(`${assertion.key_ref} stored`);
+    progress(ok(`key stored — it acts as ${key.client_email}`));
+  }
+
+  const subject = await askForSubject(assertion, prompter);
+
+  await credentials.set(
+    credentialRefForConnection(manifest, connectionId)!,
+    JSON.stringify({
+      grant: ASSERTION_GRANT,
+      key_ref: assertion.key_ref,
+      ...(subject ? { subject } : {}),
+    }),
+  );
+
+  progress(ok(subject ? `authenticated as ${subject}` : 'authenticated'));
+}
+
+/**
+ * Who the key acts as, where it acts as anyone.
+ *
+ * Blank is a real answer when delegation is `optional` — the key is then an
+ * identity in its own right. It is refused when delegation is `required`,
+ * because the alternative is a credential that authenticates perfectly and
+ * finds nothing: there is no mailbox or contact list belonging to a key, so
+ * every call would return an empty result rather than an error, which is the
+ * worst way for this to be wrong.
+ */
+async function askForSubject(
+  assertion: AuthAssertion,
+  prompter: Prompter,
+): Promise<string | undefined> {
+  const optional = assertion.delegation === 'optional';
+
+  if (!prompter.interactive) {
+    if (optional) return undefined;
+    throw new Error(
+      `This provider can only reach an account by acting as someone, and this run is ` +
+        `non-interactive so there is nobody to ask who. Re-run in a terminal.`,
+    );
+  }
+
+  progress();
+  const answer = await prompter.ask(
+    `  ${assertion.subject_label}${optional ? style.dim(' [none]') : ''}`,
+  );
+
+  if (answer.length > 0) return answer;
+
+  if (optional) return undefined;
+
+  throw new Error(
+    `${assertion.subject_label} is required here: this provider has nothing that belongs to a ` +
+      'key, so a connection that acts as nobody would authenticate and then find every ' +
+      'mailbox, list and calendar empty.',
+  );
+}

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

@@ -16,9 +16,14 @@ import { ensureOAuthApp } from './setup.ts';
 /**
  * Getting a token, and saying what it will be able to do first.
  *
- * Two paths, because two kinds of upstream: an MCP server publishes metadata
- * worth discovering and the SDK drives it, while a plain REST API announces
- * nothing and the manifest has to name its endpoints.
+ * Two paths, and what chooses between them is not the kind of upstream but
+ * whether the manifest names its own endpoints. Without them there is nothing
+ * to authorise against but what the server advertises, so the SDK discovers it
+ * and drives the flow. With them there is nothing left to discover, and the
+ * flow is ours — which is the only arrangement in which a client somebody else
+ * holds can redeem the code. A REST API never announces an authorization
+ * server, so it is always on the second path; an MCP server may be on either.
+ * See ADR-040.
  */
 
 /**
@@ -65,8 +70,8 @@ export async function authorise(input: {
   /** How the operator spelled the target, so a refusal names a command they typed. */
   target?: string;
   profile: string;
-  /** `--own-client`: register a client rather than using the one a broker runs. */
-  ownClient?: boolean;
+  /** Which OAuth client, when the operator chose one. `undefined` keeps today's precedence. */
+  client?: 'own' | 'hosted' | undefined;
   prompter?: Prompter;
   /** The operator has already said yes to scopes broader than the provider needs. */
   acceptBroadScopes?: boolean;
@@ -86,13 +91,24 @@ export async function authorise(input: {
   // announces. So the manifest names the endpoints and we run the flow
   // directly — the same loopback listener, PKCE, and exchange, minus the
   // discovery the SDK would otherwise do for us.
-  if (manifest.connector.kind !== 'mcp') {
+  //
+  // An MCP connector takes that path too when it names both endpoints, and that
+  // is the *only* thing declaring them means. The SDK's flow ends by posting to
+  // the token endpoint with whatever `clientInformation()` returned, which is
+  // fine for a client the operator holds and impossible for one held by a
+  // broker — so a provider whose client lives somewhere else opts out here
+  // rather than discovering it after consent. Nothing is lost by opting out:
+  // discovery is all the SDK was doing that this does not, and a manifest that
+  // names its endpoints has nothing left to discover. Notion, Linear, and
+  // Google's two MCP servers name neither and are untouched. See ADR-040.
+  if (
+    manifest.connector.kind !== 'mcp' ||
+    (manifest.auth.authorize_url !== undefined && manifest.auth.token_url !== undefined)
+  ) {
     await authoriseDirect(input);
     return;
   }
 
-  // An MCP provider is always bring-your-own: `defineProvider` refuses a broker
-  // on one, because the SDK owns the exchange and there is no seam to route it.
   if (manifest.auth.registration === 'manual') {
     await ensureOAuthApp(input);
   }
@@ -187,7 +203,7 @@ async function authoriseDirect(input: {
   firstForProvider: boolean;
   target?: string;
   profile: string;
-  ownClient?: boolean;
+  client?: 'own' | 'hosted' | undefined;
   prompter?: Prompter;
   acceptBroadScopes?: boolean;
   fetch?: typeof globalThis.fetch;
@@ -210,7 +226,7 @@ async function authoriseDirect(input: {
     document: input.document,
     changes: input.changes,
     firstForProvider: input.firstForProvider,
-    ownClient: input.ownClient === true,
+    client: input.client,
     target: input.target ?? manifest.id,
     profile: input.profile,
     ...(input.prompter ? { prompter: input.prompter } : {}),
@@ -234,19 +250,39 @@ async function authoriseDirect(input: {
     throw new Error('Cancelled — nothing was authorised.');
   }
 
+  // What a response carrying no refresh token means, which only the manifest
+  // knows: Google omitting one is a failure worth stopping for, Slack omitting
+  // one is the ordinary success. See `RefreshTokenPolicy`.
+  const refreshToken = {
+    required: manifest.auth.refresh_token === 'required',
+    vendor: manifest.name,
+    ...(manifest.auth.revoke_url ? { revokeUrl: manifest.auth.revoke_url } : {}),
+  };
+
   let tokens;
   try {
     tokens = await runOAuthFlow({
       authorizeUrl,
-      clientId: client.kind === 'own' ? client.clientId : client.config.clientId,
-      ...(client.kind === 'own'
-        ? { tokenUrl, clientSecret: client.clientSecret }
-        : {
+      clientId: client.kind === 'brokered' ? client.config.clientId : client.clientId,
+      ...(client.kind === 'brokered'
+        ? {
             exchange: brokerExchangeVia({
               url: client.url,
+              refreshToken,
               ...(input.fetch ? { fetch: input.fetch } : {}),
             }),
+          }
+        : {
+            tokenUrl,
+            clientSecret: client.clientSecret,
           }),
+      refreshToken,
+      // Only where the broker published one, which means only where the vendor
+      // refuses a loopback redirect. The broker owns the URL because the
+      // correct value depends on which deployment answered `/config`.
+      ...(client.kind === 'brokered' && client.config.redirectUri
+        ? { relayRedirect: client.config.redirectUri }
+        : {}),
       scopes,
       connectionLabel: manifest.name,
       ...(manifest.auth.authorize_params
@@ -283,10 +319,18 @@ async function authoriseDirect(input: {
     `${manifest.id}/${connectionId}`,
     JSON.stringify({
       access_token: tokens.accessToken,
-      refresh_token: tokens.refreshToken,
+      // Both omitted rather than defaulted where the vendor issues neither.
+      //
+      // A long-lived token has no refresh token and states no lifetime, and
+      // inventing an hour for it would have `doctor` reporting a healthy
+      // connection as stale forever while telling the operator to re-run a
+      // command that changes nothing. Absent is what `upstreamAccessToken`
+      // already reads as "hand back what is stored", which is correct here.
+      ...(tokens.refreshToken ? { refresh_token: tokens.refreshToken } : {}),
       token_type: 'Bearer',
-      expires_in: tokens.expiresIn,
-      expires_at: Date.now() + tokens.expiresIn * 1000,
+      ...(tokens.expiresIn !== undefined
+        ? { expires_in: tokens.expiresIn, expires_at: Date.now() + tokens.expiresIn * 1000 }
+        : {}),
       scope: tokens.scope,
       issuer: new URL(authorizeUrl).origin,
       ...(tokens.idToken ? { id_token: tokens.idToken } : {}),

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

@@ -5,7 +5,7 @@ import {
   brokerOriginOverride,
   type BrokerConfig,
 } from '#connectivity/auth/index.ts';
-import type { ProviderManifest } from '#connectivity';
+import { hasOwnClientPath, type ProviderManifest } from '#connectivity';
 import type { SecretStore } from '#secrets';
 import { ConfigDocument } from '../../config-edit.ts';
 import { progress, style, warn } from '../../output.ts';
@@ -38,8 +38,15 @@ export interface ClientChoice {
   readonly changes: string[];
   /** No connection of this provider exists yet, so its console setup is undone. */
   readonly firstForProvider: boolean;
-  /** `--own-client`: register one rather than using the client the broker runs. */
-  readonly ownClient: boolean;
+  /**
+   * Which client, when the operator said which.
+   *
+   * `undefined` is the precedence this file has always applied and is what a
+   * provider with one browser route resolves to: a declared `oauth_apps` entry
+   * wins, otherwise the broker. The two explicit values come from the choice
+   * `connect` now prints, and they override that precedence in both directions.
+   */
+  readonly client: 'own' | 'hosted' | undefined;
   /** How the operator spelled the target, so a refusal names a command they typed. */
   readonly target: string;
   readonly profile: string;
@@ -54,9 +61,31 @@ export async function resolveOAuthClient(input: ClientChoice): Promise<OAuthClie
   }
 
   const { app, broker } = manifest.auth;
+  const ownClient = input.client === 'own';
+  // Hoisted: four of the branches below need the answer, and it reads the store.
+  const hasOwnClient = await profileHasOwnClient(app, document, credentials);
+
+  // Asked for outright, on a profile that registered a client of its own.
+  //
+  // Honoured rather than overruled, which is a change: the entry used to be
+  // final. It can be honoured safely because which client minted a token is
+  // stamped on the token — so this connection refreshes against the broker
+  // while every existing one keeps refreshing where it was issued. What it must
+  // not be is silent, because the profile's other connections do not move.
+  const insteadOfOwn = input.client === 'hosted' && broker !== undefined && hasOwnClient;
+
+  if (insteadOfOwn) {
+    progress(
+      style.dim(
+        `This profile has an OAuth client of its own, and this connection is being authorised ` +
+          `against ${broker.operator}'s instead. Existing connections are unaffected — they keep ` +
+          `refreshing against the client that issued them.`,
+      ),
+    );
+  }
 
-  if (!broker || (await profileHasOwnClient(app, document, credentials)) || input.ownClient) {
-    if (input.ownClient && broker && !hasClientPrompts(manifest)) {
+  if (!broker || (!insteadOfOwn && (hasOwnClient || ownClient))) {
+    if (ownClient && broker && !hasOwnClientPath(manifest)) {
       // `defineProvider` permits a broker with no prompts — a provider with no
       // bring-your-own path is a legal thing to be. This is where that absence
       // becomes a sentence rather than a prompt for a value nothing collects.
@@ -73,7 +102,7 @@ export async function resolveOAuthClient(input: ClientChoice): Promise<OAuthClie
       firstForProvider: input.firstForProvider,
       ...(input.prompter ? { prompter: input.prompter } : {}),
     });
-    if (input.ownClient) declareOwnClient(document, manifest, input.changes);
+    if (ownClient) declareOwnClient(document, manifest, input.changes);
 
     const [clientId, clientSecret] = app
       ? await Promise.all([
@@ -116,6 +145,7 @@ export async function resolveOAuthClient(input: ClientChoice): Promise<OAuthClie
       cause: cause instanceof Error ? cause.message : String(cause),
       ...(cause instanceof BrokerError && cause.notice ? { notice: cause.notice } : {}),
       docsUrl: broker.docs_url,
+      ownClient: hasOwnClientPath(manifest),
     });
   }
 
@@ -128,6 +158,7 @@ export async function resolveOAuthClient(input: ClientChoice): Promise<OAuthClie
       cause: 'it is not accepting new connections.',
       ...(config.notice ? { notice: config.notice } : {}),
       docsUrl: config.docsUrl ?? broker.docs_url,
+      ownClient: hasOwnClientPath(manifest),
     });
   }
 
@@ -193,9 +224,6 @@ async function profileHasOwnClient(
   return Boolean(id && secret);
 }
 
-function hasClientPrompts(manifest: ProviderManifest): boolean {
-  return (manifest.setup?.prompts ?? []).some((prompt) => prompt.scope === 'shared');
-}
 
 /**
  * What is actually asked for, and what the broker cannot grant.

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

@@ -0,0 +1,94 @@
+import { bearerTokenAsStored } from '#connectivity/auth/index.ts';
+import type { AnyConnector, DiscoveredCapability, ProviderManifest } from '#connectivity';
+import { createMcpConnector } from '#connectivity/transports';
+import type { RegisteredProvider } from '#registry';
+import type { SecretStore } from '#secrets';
+import { progress, style } from '../../output.ts';
+
+/**
+ * Step three of `connect`: ask the upstream what it exposes.
+ *
+ * A manifest never declares capabilities for a proxied server — the server is
+ * the source of truth, and a declared list would go stale the moment the vendor
+ * ships. So this is the one part of connecting that talks to the thing being
+ * connected for a reason other than authentication.
+ *
+ * Its own file because the three cases have nothing to do with one another: an
+ * MCP server is asked over a session, an HTTP provider is read from a
+ * description on disk, and a local provider already knows. Interleaved with the
+ * config writing around them, that was three shapes wearing one `if`.
+ */
+
+/**
+ * What discovery is actually doing, per kind, so the wait is explained.
+ *
+ * They differ enough to be worth saying: reading a local OpenAPI file is
+ * instant, while signing in to an IMAP server is a TLS handshake and a LOGIN
+ * against a host that sometimes takes its time.
+ */
+const DISCOVERY_NOTE: Record<string, string> = {
+  mcp: 'Discovering capabilities…',
+  http: 'Reading the API description…',
+};
+
+export async function discoverCapabilities(input: {
+  readonly entry: RegisteredProvider;
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly credentials: SecretStore;
+  readonly connectorFor: (providerId: string, connectionId: string) => AnyConnector | undefined;
+  /** Called with what was found, so the caller can cache and register it. */
+  readonly remember: (discovered: DiscoveredCapability[]) => Promise<void>;
+}): Promise<DiscoveredCapability[]> {
+  const { entry, manifest, connectionId, credentials } = input;
+
+  if (manifest.connector.kind === 'local') return localCapabilities(entry, manifest);
+
+  progress(style.dim(DISCOVERY_NOTE[manifest.connector.kind] ?? 'Discovering capabilities…'));
+
+  // MCP is the one kind that does not use the runtime's connector here: it
+  // wants the token exactly as just written, without the refresh machinery that
+  // `bearerToken` wraps around it. Every other kind carries whatever credential
+  // it needs from the factory.
+  const connector =
+    manifest.connector.kind === 'mcp'
+      ? createMcpConnector({
+          endpoint: manifest.connector.endpoint,
+          ...(manifest.connector.headers ? { headers: manifest.connector.headers } : {}),
+          accessToken: () => bearerTokenAsStored(manifest, connectionId, credentials),
+        })
+      : input.connectorFor(manifest.id, connectionId);
+
+  if (!connector) return [];
+
+  // Discovery takes the manifest and nothing else. What a provider exposes is a
+  // property of the provider, not of an account — which is just as well,
+  // because the connection being created does not exist in config until the
+  // step after this one.
+  const discovered = await connector.discover({ manifest });
+  await input.remember(discovered);
+  return discovered;
+}
+
+/**
+ * Local capabilities carry their bundle from the manifest.
+ *
+ * Resources are included alongside tools: they need a policy grant too, and
+ * leaving them out would register a resource nothing is allowed to read.
+ */
+function localCapabilities(
+  entry: RegisteredProvider,
+  manifest: ProviderManifest,
+): DiscoveredCapability[] {
+  if (!entry.definition) return [];
+
+  const bundleOf = (name: string): string | undefined =>
+    manifest.bundles?.find((candidate) => candidate.capabilities.includes(name))?.name;
+
+  return entry.definition.capabilities.map((capability) => ({
+    name: capability.name,
+    description: capability.description,
+    inputSchema: {},
+    ...(bundleOf(capability.name) ? { bundle: bundleOf(capability.name)! } : {}),
+  }));
+}

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

@@ -0,0 +1,72 @@
+import type { ProviderRegistry } from '#registry';
+import { progress, style } from '../../output.ts';
+import { credentialApp, familyNote } from './accounts.ts';
+import { familyOutcome, type ConnectOutcome } from './outcome.ts';
+
+/**
+ * `lanes link connect icloud` — an account rather than a provider.
+ *
+ * Everyone models iCloud this way: Apple's own Settings, macOS Internet
+ * Accounts, Thunderbird, DAVx⁵. One authorisation, three services. It is three
+ * *providers* underneath because mail and calendars are different protocols,
+ * and because a policy line per provider is what lets someone allow
+ * `icloud_calendar.*` while never granting mail — but nobody should have to
+ * know that to connect their account.
+ *
+ * Its own file because it is its own subject: `runConnect` is five numbered
+ * steps that add one account, and this is the fan-out that turns one name into
+ * several of those. Keeping them together made the interesting half — how a
+ * partial failure is reported — read as a preamble to be scrolled past.
+ */
+
+/**
+ * Which providers answer to this name as a shared account.
+ *
+ * Fewer than two is not a family. Asked of the registry rather than matched on
+ * the id, for the reason `siblingAccountId` gives: `app` is a manifest field,
+ * and a provider is free to declare `app: icloud` under any name it likes.
+ */
+export function familyMembers(registry: ProviderRegistry, name: string): readonly string[] {
+  return registry
+    .list()
+    .filter((candidate) => credentialApp(candidate.manifest) === name)
+    .map((candidate) => candidate.manifest.id);
+}
+
+/**
+ * Connect each member in turn, and report the account rather than the services.
+ *
+ * In sequence, and the order matters: the first settles the account id and
+ * stores the credential, and the rest find both already there.
+ *
+ * The id travels as a flag because the family members are addressed by their
+ * own names — `connect icloud.will` parses `will` off a target that is then
+ * thrown away, and recursing without it meant the command named an account and
+ * each member silently invented its own.
+ *
+ * `announced` is passed for the same reason and one axis over: the line naming
+ * the target belongs to the account, not to each service under it, so it is
+ * printed once here and suppressed in every member. Three copies of it is three
+ * times nothing new.
+ */
+export async function connectFamily<Options extends { readonly id?: string | undefined }>(input: {
+  readonly name: string;
+  readonly members: readonly string[];
+  readonly options: Options;
+  readonly namedId: string | undefined;
+  readonly connect: (
+    provider: string,
+    options: Options,
+    announced: boolean,
+  ) => Promise<ConnectOutcome>;
+}): Promise<ConnectOutcome> {
+  const { name, members, options, namedId, connect } = input;
+
+  progress(style.dim(familyNote(name, members)));
+
+  const inherited = { ...options, id: options.id ?? namedId };
+  const outcomes: ConnectOutcome[] = [];
+  for (const member of members) outcomes.push(await connect(member, inherited, true));
+
+  return familyOutcome(outcomes);
+}