Function start

packages/core/sdk/src/oauth-service.ts:1679–2132

(
    input: OAuthStartInput,
  )

  // start — begin a flow through a client to mint a connection.
  // -----------------------------------------------------------------------
  const start = (
    input: OAuthStartInput,
  ): Effect.Effect<ConnectResult, OAuthStartError | OrgWriteDeniedError | StorageFailure> =>
    Effect.gen(function* () {
      // Gate before any session row or upstream exchange: minting a Workspace
      // connection (including a reconnect that would replace its credential)
      // is a workspace-level change. Personal connections remain member-owned.
      yield* deps.guardOrgWrite(input.owner);
      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,
          }),
      });
      // The integration must exist BEFORE any session or provider round trip.
      // A stale reference (a connection whose integration was removed, or an
      // agent replaying an old slug) would otherwise complete authorization at
      // the provider and fail only at the mint.
      if (!(yield* deps.integrationExists(input.integration))) {
        return yield* new OAuthStartError({
          message: `Integration not found: ${String(input.integration)}`,
        });
      }
      // 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.
      // First-party apps are deployment-owned, outside the owner lattice
      // entirely, so the rule does not apply to them.
      const firstPartyFlow = isFirstPartyOAuthClientSlug(String(input.client));
      yield* Effect.annotateCurrentSpan({
        "executor.oauth.client_first_party": firstPartyFlow,
      });
      if (!firstPartyFlow && 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}`,
        });
      }

      // Normalize the name the same way the mint stores it, so the free-name
      // guard below compares against the exact stored form.
      const requestedName = connectionIdentifier(String(input.name));
      // 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