@structured-id/ui-core 4.5.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -42,7 +42,7 @@
     "@protobuf-ts/grpcweb-transport": "^2.11.1",
     "@protobuf-ts/runtime": "^2.11.1",
     "@protobuf-ts/runtime-rpc": "^2.11.1",
-    "@structured-id/proto": "^0.5.0",
+    "@structured-id/proto": "^0.6.0",
     "@structured-world/structured-email-address-ts": "^0.0.22",
     "@structured-world/structured-public-domains": "0.0.x",
     "libphonenumber-js": "^1.13.15"
@@ -79,6 +79,6 @@
       "optional": true
     }
   },
-  "packageManager": "yarn@4.14.1",
+  "packageManager": "yarn@4.18.1",
   "license": "AGPL-3.0-only"
 }

package/src/profile/composables/index.ts

@@ -7,3 +7,4 @@ export * from "./useIdentityApi";
 export * from "./useSecurityLevel";
 export * from "./useCurrentPasswordRequirement";
 export * from "./usePasswordPolicy";
+export * from "./useUpstreamSignIn";

package/src/profile/composables/useUpstreamSignIn.test.ts

@@ -0,0 +1,275 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { setActivePinia, createPinia } from "pinia";
+import { createApp, defineComponent } from "vue";
+import { createRouter, createMemoryHistory } from "vue-router";
+import {
+  abandonUpstream,
+  completeUpstream,
+  startUpstream,
+  useUpstreamCallback,
+  type UpstreamApi,
+  type UpstreamBrowser,
+} from "./useUpstreamSignIn";
+import { UPSTREAM_CALLBACK_PATH, peekUpstream } from "../upstream";
+
+vi.mock("../../composables/useBffAuth", () => ({
+  checkBffSession: vi.fn().mockResolvedValue(null),
+}));
+
+const ORIGIN = "https://ee.sid.example.com";
+const ISSUER = "https://sid.example.com";
+const RD = `${ISSUER}/i/0123456789abcdef0123456789abcdef/oauth2/authorize?client_id=ops&request_uri=${encodeURIComponent("urn:ietf:params:oauth:request_uri:r")}`;
+
+function api(outcome: "signed-in" | "linking-required" = "signed-in") {
+  return {
+    list: vi.fn().mockResolvedValue([]),
+    initiate: vi.fn().mockResolvedValue({
+      authorizationUrl:
+        "https://central.sid.example.com/i/h/oauth2/authorize?x=1",
+      stateToken: "s1",
+    }),
+    complete: vi.fn().mockResolvedValue(outcome),
+  } satisfies UpstreamApi;
+}
+
+function browser(): UpstreamBrowser & { left: string[] } {
+  const left: string[] = [];
+  return {
+    origin: ORIGIN,
+    storage: sessionStorage,
+    callbackPath: UPSTREAM_CALLBACK_PATH,
+    leaveTo: (url) => left.push(url),
+    left,
+  };
+}
+
+beforeEach(() => sessionStorage.clear());
+
+describe("startUpstream", () => {
+  // The issuer starts the sign-in for this origin's exact callback page; the
+  // browser leaves for the provider with the request kept under its state.
+  it("starts at the issuer and leaves for the provider", async () => {
+    const calls = api();
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    expect(calls.initiate).toHaveBeenCalledWith(
+      "p1",
+      `${ORIGIN}${UPSTREAM_CALLBACK_PATH}`,
+    );
+    expect(page.left).toEqual([
+      "https://central.sid.example.com/i/h/oauth2/authorize?x=1",
+    ]);
+    expect(peekUpstream(sessionStorage, "s1")).toEqual({
+      provider: "p1",
+      rd: RD,
+    });
+  });
+
+  // A refused start keeps nothing and leaves nowhere.
+  it("keeps nothing when the issuer refuses", async () => {
+    const calls = api();
+    calls.initiate.mockRejectedValue(new Error("refused"));
+    const page = browser();
+    await expect(startUpstream("p1", RD, calls, page)).rejects.toThrow(
+      "refused",
+    );
+    expect(page.left).toEqual([]);
+    expect(sessionStorage.length).toBe(0);
+  });
+});
+
+describe("abandonUpstream", () => {
+  // A provider's error return (RFC 6749 §4.1.2.1) still carries the state:
+  // the kept entry is taken, so the waiting request is offered again and
+  // nothing is left behind.
+  it("takes the kept request of a refused return", async () => {
+    const page = browser();
+    await startUpstream("p1", RD, api(), page);
+    expect(abandonUpstream("s1", page)).toBe(RD);
+    expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
+    expect(abandonUpstream("s1", page)).toBeNull();
+  });
+});
+
+describe("completeUpstream", () => {
+  // The return completes at the issuer with the provider and the callback
+  // URI it started with, and continues the kept request.
+  it("completes the sign-in this tab started", async () => {
+    const calls = api();
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    const done = await completeUpstream("c1", "s1", calls, page);
+    expect(calls.complete).toHaveBeenCalledWith(
+      "p1",
+      "c1",
+      "s1",
+      `${ORIGIN}${UPSTREAM_CALLBACK_PATH}`,
+    );
+    expect(done).toEqual({ outcome: "signed-in", rd: RD });
+  });
+
+  // A return this tab did not start, or one already completed, asks the
+  // issuer nothing.
+  it("completes nothing it did not start, and nothing twice", async () => {
+    const calls = api();
+    const page = browser();
+    expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
+      outcome: "unknown",
+    });
+    await startUpstream("p1", RD, calls, page);
+    await completeUpstream("c1", "s1", calls, page);
+    expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
+      outcome: "unknown",
+    });
+    expect(calls.complete).toHaveBeenCalledTimes(1);
+  });
+
+  // An upstream account the issuer does not know is no sign-in.
+  it("reports an account that needs linking", async () => {
+    const calls = api("linking-required");
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
+      outcome: "linking-required",
+      rd: RD,
+    });
+  });
+});
+
+/** The callback composable on a real router at `at`. */
+async function callbackAt(
+  at: string,
+  calls: UpstreamApi,
+  page: UpstreamBrowser,
+) {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: UPSTREAM_CALLBACK_PATH, component: { template: "<div />" } },
+      { path: "/account", component: { template: "<div />" } },
+    ],
+  });
+  await router.push(at);
+  await router.isReady();
+  const pinia = createPinia();
+  setActivePinia(pinia);
+  const left: string[] = [];
+  let result!: ReturnType<typeof useUpstreamCallback>;
+  const app = createApp(
+    defineComponent({
+      setup() {
+        result = useUpstreamCallback("/account", {
+          issuerOrigin: ISSUER,
+          leaveTo: (url) => left.push(url),
+          api: calls,
+          browser: page,
+        });
+        return () => null;
+      },
+    }),
+  );
+  app.use(pinia);
+  app.use(router);
+  app.mount(document.createElement("div"));
+  return { result, router, left };
+}
+
+describe("useUpstreamCallback", () => {
+  // The kept request continues at the issuer.
+  it("continues the request kept for the state", async () => {
+    const calls = api();
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    const { result, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(result.failure.value).toBeNull();
+    expect(left).toEqual([RD]);
+  });
+
+  // A sign-in started without a request enters the app: an rd added to the
+  // callback URL is not continued, whatever it names.
+  it("continues no request named only by the callback's own query", async () => {
+    const calls = api();
+    const page = browser();
+    await startUpstream("p1", null, calls, page);
+    const { result, router, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1&rd=${encodeURIComponent(RD)}`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(left).toEqual([]);
+    expect(router.currentRoute.value.path).toBe("/account");
+  });
+
+  // A provider error takes the kept entry and keeps its request for signing
+  // in another way; nothing is completed at the issuer.
+  it("answers a provider error with the waiting request", async () => {
+    const calls = api();
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    const { result } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?error=access_denied&state=s1`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(result.failure.value).toBe("provider-error");
+    expect(result.continued.value).toBe(RD);
+    expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
+    expect(calls.complete).not.toHaveBeenCalled();
+  });
+
+  // The issuer failing the completion still answers the waiting request:
+  // the kept entry is gone (one-shot), so its rd must reach the page.
+  it("keeps the waiting request when the issuer fails", async () => {
+    const calls = api();
+    calls.complete.mockRejectedValue(new Error("unavailable"));
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    const { result, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(result.failure.value).toBe("failed");
+    expect(result.continued.value).toBe(RD);
+    expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
+    expect(left).toEqual([]);
+  });
+
+  // A return this tab did not start signs nobody in.
+  it("completes nothing this tab did not start", async () => {
+    const calls = api();
+    const { result, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
+      calls,
+      browser(),
+    );
+    await result.complete();
+    expect(result.failure.value).toBe("unknown");
+    expect(calls.complete).not.toHaveBeenCalled();
+    expect(left).toEqual([]);
+  });
+
+  // An account that needs linking is reported with its waiting request.
+  it("reports linking with the waiting request", async () => {
+    const calls = api("linking-required");
+    const page = browser();
+    await startUpstream("p1", RD, calls, page);
+    const { result, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(result.failure.value).toBe("linking-required");
+    expect(result.continued.value).toBe(RD);
+    expect(left).toEqual([]);
+  });
+});

package/src/profile/composables/useUpstreamSignIn.ts

@@ -0,0 +1,280 @@
+/**
+ * Sign-in through the upstream identity providers the issuer trusts, over
+ * the sign-in surface's transport. See `../upstream` for what is kept
+ * between leaving for the provider and its return.
+ */
+import { ref } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { getTransport } from "../../index";
+import type { EnabledProviderInfo } from "@structured-id/proto/sid/v1/federation/upstream";
+import { UpstreamServiceClient } from "@structured-id/proto/sid/v1/federation/upstream.client";
+import {
+  UPSTREAM_CALLBACK_PATH,
+  rememberUpstream,
+  takeUpstream,
+  upstreamCallbackUri,
+} from "../upstream";
+import { useLoginSuccess, type LoginSuccessOptions } from "./useLoginSuccess";
+
+export type { EnabledProviderInfo };
+
+/** The calls a sign-in makes; the issuer's upstream service by default. */
+export interface UpstreamApi {
+  list(): Promise<EnabledProviderInfo[]>;
+  initiate(
+    provider: string,
+    redirectUri: string,
+  ): Promise<{ authorizationUrl: string; stateToken: string }>;
+  complete(
+    provider: string,
+    code: string,
+    state: string,
+    redirectUri: string,
+  ): Promise<"signed-in" | "linking-required">;
+}
+
+/** The issuer's upstream service on the sign-in surface. */
+export function upstreamApi(): UpstreamApi {
+  const client = () => new UpstreamServiceClient(getTransport());
+  return {
+    async list() {
+      const { response } = await client().listEnabledProviders({});
+      return [...response.providers].sort(
+        (a, b) => a.displayOrder - b.displayOrder,
+      );
+    },
+    async initiate(provider, redirectUri) {
+      const { response } = await client().initiateUpstreamAuth({
+        providerId: provider,
+        redirectUri,
+      });
+      return response;
+    },
+    async complete(provider, code, state, redirectUri) {
+      const { response } = await client().handleUpstreamCallback({
+        providerId: provider,
+        code,
+        state,
+        redirectUri,
+      });
+      switch (response.result.oneofKind) {
+        case "success":
+          return "signed-in";
+        case "linkingRequired":
+          return "linking-required";
+        default:
+          throw new Error("The issuer answered no sign-in outcome");
+      }
+    },
+  };
+}
+
+/** Where the browser goes and what it keeps: the page's by default. */
+export interface UpstreamBrowser {
+  origin: string;
+  storage: Storage;
+  /** The app's callback page path. */
+  callbackPath: string;
+  leaveTo(url: string): void;
+}
+
+/** The current page, returning to `callbackPath`. */
+export function pageBrowser(
+  callbackPath: string = UPSTREAM_CALLBACK_PATH,
+): UpstreamBrowser {
+  return {
+    origin: window.location.origin,
+    storage: sessionStorage,
+    callbackPath,
+    leaveTo: (url) => window.location.assign(url),
+  };
+}
+
+/**
+ * Leave for `provider`, keeping the request `rd` for the return: the issuer
+ * starts the sign-in for this origin's callback page.
+ */
+export async function startUpstream(
+  provider: string,
+  rd: string | null,
+  api: UpstreamApi = upstreamApi(),
+  browser: UpstreamBrowser = pageBrowser(),
+): Promise<void> {
+  const started = await api.initiate(
+    provider,
+    upstreamCallbackUri(browser.origin, browser.callbackPath),
+  );
+  rememberUpstream(browser.storage, started.stateToken, { provider, rd });
+  browser.leaveTo(started.authorizationUrl);
+}
+
+/**
+ * Give up the return carrying `state`, which the provider answered with an
+ * error (RFC 6749 §4.1.2.1): its kept entry is taken, and the request it
+ * waited for, if any, is answered for signing in another way.
+ */
+export function abandonUpstream(
+  state: string,
+  browser: UpstreamBrowser = pageBrowser(),
+): string | null {
+  return takeUpstream(browser.storage, state)?.rd ?? null;
+}
+
+/** How a return to the callback page ended. */
+export type UpstreamReturn =
+  | {
+      /** `failed`: the issuer could not complete it. */
+      outcome: "signed-in" | "linking-required" | "failed";
+      rd: string | null;
+    }
+  | { outcome: "unknown" };
+
+/**
+ * Complete the return carrying `code` and `state` at the issuer: once, for
+ * the sign-in this tab started. A return this tab did not start, or one
+ * already completed, is `unknown`. Every other outcome, a failed one
+ * included, carries the request the return waited for: its kept entry is
+ * already taken.
+ */
+export async function completeUpstream(
+  code: string,
+  state: string,
+  api: UpstreamApi = upstreamApi(),
+  browser: UpstreamBrowser = pageBrowser(),
+): Promise<UpstreamReturn> {
+  const pending = takeUpstream(browser.storage, state);
+  if (!pending) return { outcome: "unknown" };
+  try {
+    const outcome = await api.complete(
+      pending.provider,
+      code,
+      state,
+      upstreamCallbackUri(browser.origin, browser.callbackPath),
+    );
+    return { outcome, rd: pending.rd };
+  } catch {
+    return { outcome: "failed", rd: pending.rd };
+  }
+}
+
+/** Options of the upstream sign-in composables. */
+export interface UpstreamSignInOptions {
+  /** The app's callback page path; {@link UPSTREAM_CALLBACK_PATH} by default. */
+  callbackPath?: string;
+  api?: UpstreamApi;
+  browser?: UpstreamBrowser;
+}
+
+/** The login page's providers and their buttons. */
+export function useUpstreamSignIn(
+  rd: () => string | null,
+  options: UpstreamSignInOptions = {},
+) {
+  const providers = ref<EnabledProviderInfo[]>([]);
+  const loading = ref<string | null>(null);
+  const error = ref<string | null>(null);
+  const api = () => options.api ?? upstreamApi();
+
+  async function load() {
+    try {
+      providers.value = await api().list();
+    } catch {
+      // Without its providers the page still signs in another way.
+      providers.value = [];
+    }
+  }
+
+  async function signInWith(provider: string) {
+    loading.value = provider;
+    error.value = null;
+    try {
+      await startUpstream(
+        provider,
+        rd(),
+        api(),
+        options.browser ?? pageBrowser(options.callbackPath),
+      );
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : "Sign-in failed";
+      loading.value = null;
+    }
+  }
+
+  return { providers, loading, error, load, signInWith };
+}
+
+/** Why a return to the callback page signed nobody in. */
+export type UpstreamFailure =
+  /** The provider refused, or the user cancelled there. */
+  | "provider-error"
+  /** The return carried no code or no state. */
+  | "no-return"
+  /** This tab did not start the sign-in, or already completed it. */
+  | "unknown"
+  /** The upstream account is linked to no Profile here. */
+  | "linking-required"
+  /** The issuer could not complete it. */
+  | "failed";
+
+/**
+ * The callback page: completes the provider's return once and continues
+ * the authorization request kept for its `state` through
+ * {@link useLoginSuccess}, or into the app at `redirectTo`. The callback's
+ * own query is replaced first, so an `rd` added to it is never continued.
+ */
+export function useUpstreamCallback(
+  redirectTo: string,
+  options: UpstreamSignInOptions & LoginSuccessOptions = {},
+) {
+  const route = useRoute();
+  const router = useRouter();
+  const { onLoginSuccess } = useLoginSuccess(redirectTo, options);
+  const failure = ref<UpstreamFailure | null>(null);
+  /** The request a failed return still waits for, to sign in another way. */
+  const continued = ref<string | null>(null);
+  const browser = () => options.browser ?? pageBrowser(options.callbackPath);
+
+  function text(value: unknown): string | null {
+    return typeof value === "string" && value ? value : null;
+  }
+
+  async function complete() {
+    const code = text(route.query.code);
+    const state = text(route.query.state);
+    if (text(route.query.error)) {
+      if (state) continued.value = abandonUpstream(state, browser());
+      failure.value = "provider-error";
+      return;
+    }
+    if (!code || !state) {
+      failure.value = "no-return";
+      return;
+    }
+    try {
+      const done = await completeUpstream(
+        code,
+        state,
+        options.api ?? upstreamApi(),
+        browser(),
+      );
+      if (done.outcome === "unknown") {
+        failure.value = "unknown";
+        return;
+      }
+      continued.value = done.rd;
+      if (done.outcome !== "signed-in") {
+        failure.value = done.outcome;
+        return;
+      }
+      await router.replace({
+        path: route.path,
+        query: done.rd ? { rd: done.rd } : {},
+      });
+      await onLoginSuccess();
+    } catch {
+      failure.value = "failed";
+    }
+  }
+
+  return { failure, continued, complete };
+}

package/src/profile/index.ts

@@ -14,5 +14,8 @@ export * from "./composables";
 // Slot-based form components
 export * from "./components";
 
+// Upstream identity provider sign-in: what a return keeps
+export * from "./upstream";
+
 // Auth helper
 export { authMeta } from "./auth";

package/src/profile/upstream.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  UPSTREAM_CALLBACK_PATH,
+  peekUpstream,
+  rememberUpstream,
+  takeUpstream,
+  upstreamCallbackUri,
+  upstreamRequestOfPage,
+} from "./upstream";
+
+const RD =
+  "https://sid.example.com/i/0123456789abcdef0123456789abcdef/oauth2/authorize?client_id=ops&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Ar";
+
+function location(path: string) {
+  const url = new URL(path, "https://ee.sid.example.com");
+  return { pathname: url.pathname, search: url.search };
+}
+
+beforeEach(() => sessionStorage.clear());
+
+describe("upstreamCallbackUri", () => {
+  // The provider returns to one exact URI registered for this origin, with
+  // no query: the provider compares it exactly (RFC 6749 §3.1.2).
+  it("is the callback page on this origin", () => {
+    expect(upstreamCallbackUri("https://ee.sid.example.com")).toBe(
+      `https://ee.sid.example.com${UPSTREAM_CALLBACK_PATH}`,
+    );
+    expect(
+      upstreamCallbackUri("https://admin.sid.example.com", "/upstream/return"),
+    ).toBe("https://admin.sid.example.com/upstream/return");
+  });
+});
+
+describe("the kept return", () => {
+  // The return to the callback page finds the provider and the request it
+  // started with, under the provider's state.
+  it("is found under its state", () => {
+    rememberUpstream(sessionStorage, "s1", { provider: "p1", rd: RD });
+    expect(peekUpstream(sessionStorage, "s1")).toEqual({
+      provider: "p1",
+      rd: RD,
+    });
+    expect(peekUpstream(sessionStorage, "s2")).toBeUndefined();
+  });
+
+  // A sign-in without an authorization request returns without one.
+  it("keeps the absence of a request", () => {
+    rememberUpstream(sessionStorage, "s1", { provider: "p1", rd: null });
+    expect(peekUpstream(sessionStorage, "s1")?.rd).toBeNull();
+  });
+
+  // A return completes once: taking it removes it, so a reloaded or replayed
+  // callback finds nothing to continue.
+  it("is taken once", () => {
+    rememberUpstream(sessionStorage, "s1", { provider: "p1", rd: RD });
+    expect(takeUpstream(sessionStorage, "s1")?.provider).toBe("p1");
+    expect(takeUpstream(sessionStorage, "s1")).toBeUndefined();
+  });
+
+  // A malformed or foreign entry is no return.
+  it("ignores what it did not write", () => {
+    sessionStorage.setItem("sid.upstream.s1", "not json");
+    sessionStorage.setItem("sid.upstream.s2", JSON.stringify({ rd: RD }));
+    expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
+    expect(peekUpstream(sessionStorage, "s2")).toBeUndefined();
+  });
+});
+
+describe("upstreamRequestOfPage", () => {
+  // Every other page completes the request in its query.
+  it("reads rd from the query", () => {
+    expect(
+      upstreamRequestOfPage(
+        location(`/account/login?rd=${encodeURIComponent(RD)}`),
+        sessionStorage,
+      ),
+    ).toBe(RD);
+    expect(
+      upstreamRequestOfPage(location("/account/login"), sessionStorage),
+    ).toBeNull();
+  });
+
+  // The callback page completes the request kept for its state, which the
+  // provider's return does not carry; the entry stays for the page to take.
+  // An rd in the callback's own query is never used.
+  it("reads the callback's request only from its kept return", () => {
+    rememberUpstream(sessionStorage, "s1", { provider: "p1", rd: RD });
+    const callback = location(`${UPSTREAM_CALLBACK_PATH}?code=c&state=s1`);
+    expect(upstreamRequestOfPage(callback, sessionStorage)).toBe(RD);
+    expect(peekUpstream(sessionStorage, "s1")).toBeDefined();
+    expect(
+      upstreamRequestOfPage(
+        location(`${UPSTREAM_CALLBACK_PATH}?code=c&state=other`),
+        sessionStorage,
+      ),
+    ).toBeNull();
+    expect(
+      upstreamRequestOfPage(
+        location(
+          `${UPSTREAM_CALLBACK_PATH}?state=other&rd=${encodeURIComponent(RD)}`,
+        ),
+        sessionStorage,
+      ),
+    ).toBeNull();
+  });
+
+  // An app with its own callback path reads its own callback page.
+  it("follows the app's callback path", () => {
+    rememberUpstream(sessionStorage, "s1", { provider: "p1", rd: RD });
+    expect(
+      upstreamRequestOfPage(
+        location("/upstream/return?state=s1"),
+        sessionStorage,
+        "/upstream/return",
+      ),
+    ).toBe(RD);
+  });
+});

package/src/profile/upstream.ts

@@ -0,0 +1,93 @@
+/**
+ * Sign-in through an upstream identity provider the issuer trusts. The page
+ * asks the issuer to start it, keeps what the return needs under the
+ * provider's `state` in this tab's session storage, and goes to the
+ * provider. The provider returns the browser to the callback page with
+ * `code` and `state`; the page completes the sign-in at the same issuer and
+ * continues the authorization request that sent the user there (`rd`).
+ *
+ * The kept entry is no credential: the issuer keeps the request's state,
+ * PKCE verifier and nonce itself and checks `state` on completion.
+ */
+
+/** Where the provider returns the browser, unless the app names its own. */
+export const UPSTREAM_CALLBACK_PATH = "/account/upstream/callback";
+
+/**
+ * The redirect URI registered with the provider for `origin`: exact and
+ * without a query, as the provider compares it (RFC 6749 §3.1.2).
+ */
+export function upstreamCallbackUri(
+  origin: string,
+  path: string = UPSTREAM_CALLBACK_PATH,
+): string {
+  return `${origin}${path}`;
+}
+
+/** What the return to the callback page needs. */
+export interface PendingUpstream {
+  /** The provider the sign-in started at. */
+  provider: string;
+  /** The authorization request the sign-in completes, if one sent the user. */
+  rd: string | null;
+}
+
+const PREFIX = "sid.upstream.";
+
+/** Keep `pending` for the return carrying `state`. */
+export function rememberUpstream(
+  storage: Storage,
+  state: string,
+  pending: PendingUpstream,
+): void {
+  storage.setItem(PREFIX + state, JSON.stringify(pending));
+}
+
+/** What was kept for `state`, left in place; `undefined` when nothing is. */
+export function peekUpstream(
+  storage: Storage,
+  state: string,
+): PendingUpstream | undefined {
+  const kept = storage.getItem(PREFIX + state);
+  if (kept === null) return undefined;
+  try {
+    const parsed = JSON.parse(kept) as Partial<PendingUpstream>;
+    if (typeof parsed.provider !== "string" || !parsed.provider) {
+      return undefined;
+    }
+    return {
+      provider: parsed.provider,
+      rd: typeof parsed.rd === "string" ? parsed.rd : null,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** What was kept for `state`, removed: a return completes once. */
+export function takeUpstream(
+  storage: Storage,
+  state: string,
+): PendingUpstream | undefined {
+  const pending = peekUpstream(storage, state);
+  storage.removeItem(PREFIX + state);
+  return pending;
+}
+
+/**
+ * The authorization request this page load completes: `rd` in the query, or
+ * on the callback page the one kept for its `state`. The callback's own `rd`
+ * is never used: the provider's return carries none.
+ */
+export function upstreamRequestOfPage(
+  location: Pick<Location, "pathname" | "search">,
+  storage: Storage,
+  callbackPath: string = UPSTREAM_CALLBACK_PATH,
+): string | null {
+  const query = new URLSearchParams(location.search);
+  if (location.pathname === callbackPath) {
+    const state = query.get("state");
+    return state ? (peekUpstream(storage, state)?.rd ?? null) : null;
+  }
+  return query.get("rd");
+}