Sign a user in through a window

You can let a user sign in to a site in a window of its own and bring that session back to the copy of the site your app shows inline. This page takes an inline player that shows signed out to the same player signed in, through one click, one window and one reload.

The end state is the inline frame showing the signed-in page, with the window closed by your app. What the recipe costs:

• Uses cloud.attachFrame({ iframe }), cloud.attachFrame({ window, domains }), WindowFrame.closed, WindowFrame.close, Frame.locator(...).exists(), Frame.goto, Frame.url, Frame.clearCookies, FrameWindowBlockedError, isLocatorUnsupported
• Needs nothing installed, and a page not served with Cross-Origin-Opener-Policy: same-origin
• Proven by no shipped integration yet. The production check behind @fkn/lib 0.9.35 drove the window half from a cross-site page: the attach, a locator read, close() and closed

Every step carries the [Page] badge, defined on recipes, because a window opens only from a window realm, a JavaScript execution context with a window.

[Page] Attach the player on the cloud

A window runs on the cloud backend only, and a sign-in in it reaches the frames that share its cookie jar, which are your app’s inline frames on cookies: 'persistent'. That is the default, on the root call and on cloud.attachFrame() alike, and pinning the cloud says so at the call site:

app.ts

const iframe = document.createElement('iframe')
document.querySelector('#player-slot')!.append(iframe) // in the document, in its final place, before the attach

const player = await cloud.attachFrame({ iframe, domains: ['example.org'] }) // the app's cloud cookie jar
await player.goto('https://example.org/watch')
await player.locator('.sign-in-prompt').exists() // true, the jar holds no example.org session yet

cookies stays at its default, 'persistent', which is the jar a window opened by this app uses too. With 'ephemeral' the frame gets a jar of its own and no window sign-in reaches it, and with 'native' it runs on the extension and the person’s own browser session, see the window’s cookie jar.

[Page] Open the window from the click

cloud.attachFrame({ window }) has to be the first call in the click handler. The window opens before the call’s first await, on the click’s activation, and anything awaited before it can cost the window:

app.ts

signIn.addEventListener('click', async () => {
  try {
    const login = await cloud.attachFrame({
      window: { url: 'https://example.org/login' },
      domains: ['example.org', 'accounts.example.org'], // every host the sign-in passes through
    })
    await finishSignIn(login) // the next two steps
  } catch (error) {
    if (!(error instanceof FrameWindowBlockedError)) throw error
    signIn.textContent = 'Allow pop-ups for this page, then sign in again' // nothing opened
  }
})

A popup blocker, a missing user gesture and a frame sandboxed without allow-popups all reject with FrameWindowBlockedError and open nothing. A page served with Cross-Origin-Opener-Policy: same-origin loses the window as it opens, and the attach rejects with cloud.attachFrame: the window closed before it connected, so serve it with same-origin-allow-popups.

[Page] Wait for the signed-in marker

A read at severity 0 never asks, so exists() can poll the window for something only a signed-in page shows. Race it against closed, which resolves whoever ends the window, the user included:

app.ts

// true once the signed-in marker shows, false when the window ends first
const waitForSignIn = (login: WindowFrame): Promise<boolean> => {
  const poll = async (): Promise<boolean> => {
    try {
      while (!(await login.locator('#account-menu').exists())) { // severity 0, never a card
        await new Promise(resolve => setTimeout(resolve, 1_000))
      }
      return true
    } catch (error) {
      if (isLocatorUnsupported(error)) return false // the window ended under the call
      throw error
    }
  }
  return Promise.race([poll(), login.closed.then(() => false)])
}

Every host the sign-in passes through belongs in domains. A read while the window is on a host outside them, the attach target and your goto() targets is refused with the terminal frame: this frame no longer holds the document the app attached it to, which the catch passes on rather than reading as a closed window.

[Page] Close the window and reload

Once the marker shows, close the window yourself and load the inline page again:

app.ts

const finishSignIn = async (login: WindowFrame) => {
  if (!(await waitForSignIn(login))) return // the user closed the window, and the player stays signed out
  await login.close() // commits the window's cookies to the app's jar, then closes it
  await player.goto(player.url()) // the same page again, now with the session
}

close() waits at most 2,000 ms for the window’s cookie changes to reach the jar before it closes the window, so the goto() right after it sees the session. It is idempotent and never rejects, and closed resolves once it has run.

For an app outside the fkn.app site, cookies are all that come back. A site that keeps its session in localStorage or IndexedDB signs the user in to the window alone, because the window’s site storage is its own and is cleared when it closes.

Check it worked

The inline player shows the signed-in page, and the window is gone. When it does not, take these in order:

1. FrameWindowBlockedError means something ran an await before the attach, or the page’s popups are blocked. Move the call to the top of the handler, then ask the user to allow popups.
2. cloud.attachFrame: the window closed before it connected on every click is the page’s Cross-Origin-Opener-Policy. Serve it with same-origin-allow-popups.
3. frame: this frame no longer holds the document the app attached it to from the poll means the sign-in went through a host missing from domains. Add it.
4. An ExtensionOperationUnsupportedError with operation 'attachWindow', attachFrame: a window on cookies: 'native' needs the FKN WebExtension or The FKN WebExtension does not support "attachWindow", means the window was asked for with cookies: 'native' where no extension serves one. This recipe’s player is on the cloud jar, so leave cookies at its default for the window and the player alike. A window on 'native' signs in to the person’s own browser session instead, see a window on the extension.
5. A window that signed in beside a player that still shows signed out means the player is not on the window’s jar: it was attached with cookies: 'native' or 'ephemeral', or the site keeps its session in storage rather than in cookies.

Optional: Open blank, then navigate

When the sign-in address needs an await, open the window with window: {} so the click’s activation goes to the window, then goto() the address once it is known:

app.ts

signIn.addEventListener('click', async () => {
  const login = await cloud.attachFrame({ window: {}, domains: ['example.org', 'accounts.example.org'] }) // blank, on the click's activation
  await login.goto(await loginUrl()) // the address that needed an await
})

Optional: Sign the user out

The session the window brought back lives in your app’s cloud jar, never in your app, so ending it is clearCookies() on the player, followed by the same page again:

app.ts

signOut.addEventListener('click', async () => {
  await player.clearCookies({ domain: '.example.org' }) // the example.org cookies its subdomains also receive
  await player.goto(player.url()) // the same page again, signed out
})

The jar is shared by every app of your top-level site, so this signs each of them out of example.org too. It removes only the cookies of the sites the player reaches, and never tells the site, so the session stays valid there until it lapses, see clearing cookies.

See also

• frames
• permissions and consent
• backends
• every error
• limits and timeouts