Function start

packages/core/sdk/src/oauth-service.ts:1044–1247

(
    input: OAuthStartInput,
  )

  // start — begin a flow through a client to mint a connection.
  // -----------------------------------------------------------------------
  const start = (
    input: OAuthStartInput,
  ): Effect.Effect<ConnectResult, OAuthStartError | StorageFailure> =>
    Effect.gen(function* () {
      const keys = yield* Effect.try({
        try: () => deps.ownedKeys(input.owner),
        catch: (cause) =>
          new StorageError({
            message: "Cannot start OAuth flow for owner without a subject",
            cause,
          }),
      });
      // Sharing is one-directional (org → members): a Workspace (org) connection
      // cannot be backed by a member's private (user) app. The connection owner
      // and the app owner are otherwise independent — a Personal connection
      // through a shared Workspace app is the supported cross-owner case.
      if (input.owner === "org" && input.clientOwner === "user") {
        return yield* new OAuthStartError({
          message: "A Workspace connection must use a Workspace app.",
        });
      }
      // Load the app by its EXPLICIT owner (the caller knows it — no derivation).
      // The connection is still minted under `input.owner`. Storage visibility
      // policy hides apps the actor cannot see, so a wrong owner yields null.
      const client = yield* loadClient(input.clientOwner, input.client);
      if (!client) {
        return yield* new OAuthStartError({
          message: `OAuth client not found: ${input.client}`,
        });
      }

      // newConnection: resolve the requested name to a FREE one against the
      // stored rows (not a client-side, policy-filtered view), so a second
      // untyped connect mints `personalGmail2` instead of silently re-minting
      // the first account's row. Reconnects omit the flag and keep targeting
      // their existing row. Bounded: a pathological owner with 1000 same-named
      // connections fails loudly rather than scanning forever.
      let name = input.name;
      if (input.newConnection === true) {
        let suffix = 2;
        while (
          yield* deps.connectionNameTaken({
            owner: input.owner,
            integration: input.integration,
            name,
          })
        ) {
          if (suffix > 1000) {
            return yield* new OAuthStartError({
              message: `No free connection name derivable from ${input.name}.`,
            });
          }
          name = ConnectionName.make(`${String(input.name)}${suffix}`);
          suffix++;
        }
      }

      // Declared scopes win (driven by the selected auth template). MCP-style