@structured-id/ui-core 4.14.1 → 4.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.14.1",
+  "version": "4.15.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -42,8 +42,8 @@
     "@protobuf-ts/grpcweb-transport": "^2.11.1",
     "@protobuf-ts/runtime": "^2.11.1",
     "@protobuf-ts/runtime-rpc": "^2.11.1",
-    "@structured-id/ids": "^0.4.0",
-    "@structured-id/proto": "^0.12.0",
+    "@structured-id/ids": "^0.10.0",
+    "@structured-id/proto": "^0.18.0",
     "@structured-world/structured-email-address-ts": "^0.0.22",
     "@structured-world/structured-public-domains": "0.0.x",
     "libphonenumber-js": "^1.13.15"

package/src/profile/components/SidLoginForm.vue

@@ -120,7 +120,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from "vue";
-import type { SessionId } from "@structured-id/ids";
+import type { LoginSuccessResult } from "../composables/useLoginSuccess";
 import {
   ALL_PRINCIPAL_TYPES,
   DEFAULT_PRINCIPAL_INPUT_TEXTS,
@@ -175,10 +175,7 @@ const props = withDefaults(
       identifier: string,
       password: string,
       onStep?: (step: number) => void,
-    ) => Promise<{
-      expiresIn: number;
-      sessionId?: SessionId;
-    }>;
+    ) => Promise<LoginSuccessResult & { expiresIn: number }>;
   }>(),
   {
     title: "Sign in",
@@ -207,7 +204,7 @@ const props = withDefaults(
 );
 
 const emit = defineEmits<{
-  success: [result: { expiresIn: number; sessionId?: SessionId }];
+  success: [result: LoginSuccessResult & { expiresIn: number }];
   error: [error: Error];
   "forgot-password": [];
 }>();

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

@@ -132,6 +132,7 @@ describe("createAuth prewarm", () => {
       expiresIn: 60n,
       secondFactors: [],
       enrollableFactors: [],
+      pending: null,
     });
   });
 
@@ -693,6 +694,7 @@ describe("createAuth login", () => {
       expiresIn: BigInt(3600),
       secondFactors: [],
       enrollableFactors: [],
+      pending: null,
     });
   });
 
@@ -725,9 +727,26 @@ describe("createAuth login", () => {
     expect(result).toEqual({
       sessionId: SESSION,
       expiresIn: 3600,
+      pending: null,
     });
   });
 
+  // A sign-in owing its second factor states it, for the page to continue
+  // to the factor instead of into the app.
+  it("states the second factor the sign-in owes", async () => {
+    const pending = { secondFactors: [1], enrollableFactors: [] };
+    api.loginFinish.mockResolvedValue({
+      sessionId: SESSION,
+      expiresIn: BigInt(300),
+      secondFactors: [1],
+      enrollableFactors: [],
+      pending,
+    });
+    const { login } = createAuth(loader);
+    const result = await login("alice@test.com", "pw");
+    expect(result.pending).toEqual(pending);
+  });
+
   it("propagates a wrong password (the client cannot finish)", async () => {
     vi.mocked(client.loginFinish).mockRejectedValue(
       new Error("login finish: InvalidLoginError"),

package/src/profile/composables/useAuth.ts

@@ -15,6 +15,7 @@
  * gRPC calls go through useAuthApi wrappers.
  */
 import type { CredentialId, SessionId } from "@structured-id/ids";
+import type { PendingSignIn } from "../pendingSignIn";
 import {
   completePasswordReset,
   evaluatePasswordHistory,
@@ -42,6 +43,8 @@ export interface LoginResult {
   sessionId: SessionId;
   /** Seconds until the delivered credential expires. */
   expiresIn: number;
+  /** The second factor the sign-in still owes; null when it is complete. */
+  pending: PendingSignIn | null;
 }
 
 /**
@@ -544,6 +547,7 @@ export function createAuth(loadClient: ZkppClientLoader) {
     return {
       sessionId: finished.sessionId,
       expiresIn: Number(finished.expiresIn),
+      pending: finished.pending,
     };
   }
 

package/src/profile/composables/useAuthApi.ids.test.ts

@@ -143,6 +143,8 @@ describe("passkey sign-in", () => {
     answers("webAuthnAuthenticationFinish", {
       sessionId: SESSION.toWire(),
       expiresIn: 60n,
+      secondFactors: [],
+      enrollableFactors: [],
     });
     const credential = new Uint8Array([1, 2]);
     const result = await webAuthnAuthenticationFinish(credential, "a@b.c");

package/src/profile/composables/useAuthApi.opaque.test.ts

@@ -94,7 +94,12 @@ describe("OPAQUE gRPC wrappers", () => {
   describe("opaqueLoginFinish", () => {
     it("sends principal, finalization and the login's bytes, reads the session", async () => {
       mockOpaqueLoginFinish.mockResolvedValue({
-        response: { sessionId: SESSION.toWire(), expiresIn: BigInt(3600) },
+        response: {
+          sessionId: SESSION.toWire(),
+          expiresIn: BigInt(3600),
+          secondFactors: [],
+          enrollableFactors: [],
+        },
       });
 
       const result = await opaqueLoginFinish(
@@ -110,6 +115,7 @@ describe("OPAQUE gRPC wrappers", () => {
       });
       expect(result.sessionId.equals(SESSION)).toBe(true);
       expect(result.expiresIn).toBe(BigInt(3600));
+      expect(result.pending).toBeNull();
     });
 
     // Every completed sign-in names its session; an answer without one is

package/src/profile/composables/useAuthApi.pending.test.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { RpcError } from "@protobuf-ts/runtime-rpc";
+import { OpaqueLoginId, SessionId } from "@structured-id/ids";
+import {
+  StepUpMethod,
+  opaqueLoginFinish,
+  startTotpEnrollment,
+  verifyRecoveryCode,
+  verifyTotp,
+} from "./useAuthApi";
+import { endPendingSignIn, pendingSignIn } from "../pendingSignIn";
+
+// The AuthService methods by client method name, separately for the sign-in
+// surface and the account API.
+const rpc: Record<string, Record<string, ReturnType<typeof vi.fn>>> = {
+  signIn: {},
+  account: {},
+};
+
+vi.mock("../../index", () => ({
+  getTransport: vi.fn(() => "signIn"),
+  getAccountTransport: vi.fn(() => "account"),
+}));
+
+vi.mock("@structured-id/proto/sid/v1/authn/auth.client", () => ({
+  // Called with `new`: a constructor mock must be a `function`, not an arrow.
+  AuthServiceClient: vi.fn().mockImplementation(function (surface: string) {
+    const methods = rpc[surface];
+    return new Proxy(
+      {},
+      { get: (_target, name: string) => (methods[name] ??= vi.fn()) },
+    );
+  }),
+}));
+
+vi.mock("../auth", () => ({
+  authMeta: () => ({}),
+}));
+
+const SESSION = SessionId.parse("0192f3a4-7c1e-7b2a-9d4e-3f5a6b7c8d10");
+const LOGIN = OpaqueLoginId.parse("0192f3a4-7c1e-7b2a-9d4e-3f5a6b7c8d16");
+
+function call(surface: "signIn" | "account", name: string) {
+  return (rpc[surface][name] ??= vi.fn());
+}
+
+/** The options the RPC `name` was last called with. */
+function metaOf(surface: "signIn" | "account", name: string): unknown {
+  return call(surface, name).mock.calls.at(-1)?.[1]?.meta;
+}
+
+async function signInOwingTotp() {
+  call("signIn", "opaqueLoginFinish").mockResolvedValueOnce({
+    response: {
+      sessionId: SESSION.toWire(),
+      expiresIn: 300n,
+      secondFactors: [StepUpMethod.TOTP],
+      enrollableFactors: [],
+      browserCsrf: "csrf-1",
+    },
+  });
+  return opaqueLoginFinish("alice", new Uint8Array(), LOGIN);
+}
+
+beforeEach(() => {
+  endPendingSignIn();
+  sessionStorage.clear();
+  for (const surface of Object.values(rpc)) {
+    for (const fn of Object.values(surface)) fn.mockReset();
+  }
+});
+
+describe("a browser sign-in owing its second factor", () => {
+  // Regression: the answer's factors and CSRF token were dropped, so the
+  // completion went without the token and the server refused it.
+  it("is kept from the password sign-in's answer", async () => {
+    const finished = await signInOwingTotp();
+    expect(finished.pending).toEqual({
+      secondFactors: [StepUpMethod.TOTP],
+      enrollableFactors: [],
+    });
+    expect(pendingSignIn()).toEqual(finished.pending);
+  });
+
+  it("sends its CSRF token with the completion and ends with the session", async () => {
+    await signInOwingTotp();
+    call("signIn", "verifyTotp").mockResolvedValueOnce({
+      response: { verified: true, sessionId: SESSION.toWire() },
+    });
+
+    await verifyTotp("123456");
+
+    expect(metaOf("signIn", "verifyTotp")).toEqual({
+      "x-csrf-token": "csrf-1",
+    });
+    expect(pendingSignIn()).toBeNull();
+  });
+
+  // An unknown outcome may have committed: the record stays, so the same
+  // completion is repeated with the same token and receives the sign-in.
+  it("keeps the record when the completion's outcome is unknown", async () => {
+    await signInOwingTotp();
+    call("signIn", "verifyRecoveryCode").mockRejectedValueOnce(
+      new RpcError("lost", "UNAVAILABLE"),
+    );
+
+    await expect(verifyRecoveryCode("AAAA-BBBB-CCCC")).rejects.toThrow();
+
+    expect(pendingSignIn()).not.toBeNull();
+    expect(metaOf("signIn", "verifyRecoveryCode")).toEqual({
+      "x-csrf-token": "csrf-1",
+    });
+  });
+
+  // The first TOTP enrollment of a sign-in goes to the sign-in surface with
+  // the pending token; from the account pages it stays on the account API.
+  it("enrolls its first factor on the sign-in surface", async () => {
+    await signInOwingTotp();
+    call("signIn", "startTotpEnrollment").mockResolvedValueOnce({
+      response: {},
+    });
+    call("account", "startTotpEnrollment").mockResolvedValueOnce({
+      response: {},
+    });
+
+    await startTotpEnrollment("sign-in");
+    await startTotpEnrollment();
+
+    expect(metaOf("signIn", "startTotpEnrollment")).toEqual({
+      "x-csrf-token": "csrf-1",
+    });
+    expect(metaOf("account", "startTotpEnrollment")).toEqual({});
+  });
+});

package/src/profile/composables/useAuthApi.ts

@@ -17,6 +17,7 @@ import {
   CredentialId,
   MagicLinkId,
   OpaqueLoginId,
+  OrgId,
   OtpSessionId,
   ResetSessionId,
   SessionId,
@@ -75,6 +76,12 @@ import type {
 } from "@structured-id/proto/sid/v1/authn/password_history";
 import { PasswordHistoryEvaluatorServiceClient } from "@structured-id/proto/sid/v1/authn/password_history.client";
 import { authMeta } from "../auth";
+import {
+  endPendingSignIn,
+  holdPendingSignIn,
+  pendingSignInMeta,
+  type PendingSignIn,
+} from "../pendingSignIn";
 
 /** The history evaluator: in CE served beside the credential service. */
 function evaluator(): PasswordHistoryEvaluatorServiceClient {
@@ -105,11 +112,26 @@ export type WithId<T, K extends keyof T, V> = Omit<T, K> & { [P in K]: V };
 
 // ── MFA TOTP ──
 
-export async function startTotpEnrollment(): Promise<TotpEnrollmentChallenge> {
-  const { response } = await account().startTotpEnrollment(
-    {},
-    { meta: authMeta() },
-  );
+/**
+ * Who enrolls a factor: the signed-in user from the account pages, or the
+ * pending sign-in enrolling its first factor on the sign-in surface.
+ */
+export type Enrolling = "account" | "sign-in";
+
+function enrollmentClient(by: Enrolling): {
+  client: AuthServiceClient;
+  meta: Record<string, string>;
+} {
+  return by === "sign-in"
+    ? { client: client(), meta: signInMeta() }
+    : { client: account(), meta: authMeta() };
+}
+
+export async function startTotpEnrollment(
+  by: Enrolling = "account",
+): Promise<TotpEnrollmentChallenge> {
+  const { client: enroller, meta } = enrollmentClient(by);
+  const { response } = await enroller.startTotpEnrollment({}, { meta });
   return response;
 }
 
@@ -119,13 +141,16 @@ export type TotpEnrollmentResult = WithId<
   CredentialId
 >;
 
+/**
+ * Finish the TOTP enrollment with its first code. A sign-in that enrolled
+ * its first factor then completes with a fresh code ({@link verifyTotp}).
+ */
 export async function finishTotpEnrollment(
   code: string,
+  by: Enrolling = "account",
 ): Promise<TotpEnrollmentResult> {
-  const { response } = await account().finishTotpEnrollment(
-    { code },
-    { meta: authMeta() },
-  );
+  const { client: enroller, meta } = enrollmentClient(by);
+  const { response } = await enroller.finishTotpEnrollment({ code }, { meta });
   return {
     ...response,
     credentialId: required(CredentialId, response.credentialId),
@@ -139,14 +164,26 @@ export type MfaVerifyResult = WithId<
   SessionId | undefined
 >;
 
+/**
+ * A verification's answer. The session it names ends the pending sign-in
+ * the verification completed; any failure keeps it, so the same completion
+ * can be repeated.
+ */
 function mfaVerified(response: MfaVerifyResponse): MfaVerifyResult {
-  return { ...response, sessionId: optional(SessionId, response.sessionId) };
+  const sessionId = optional(SessionId, response.sessionId);
+  if (sessionId) endPendingSignIn();
+  return { ...response, sessionId };
+}
+
+/** Metadata of a call that completes the pending sign-in, if this tab has one. */
+function signInMeta(): Record<string, string> {
+  return { ...authMeta(), ...pendingSignInMeta() };
 }
 
 export async function verifyTotp(code: string): Promise<MfaVerifyResult> {
   const { response } = await client().verifyTotp(
     { code },
-    { meta: authMeta() },
+    { meta: signInMeta() },
   );
   return mfaVerified(response);
 }
@@ -156,13 +193,13 @@ export async function verifyTotp(code: string): Promise<MfaVerifyResult> {
 export async function verifySmsMfa(code: string): Promise<MfaVerifyResult> {
   const { response } = await client().verifySmsMfa(
     { code },
-    { meta: authMeta() },
+    { meta: signInMeta() },
   );
   return mfaVerified(response);
 }
 
 export async function resendSmsMfa(): Promise<ResendSmsMfaResponse> {
-  const { response } = await client().resendSmsMfa({}, { meta: authMeta() });
+  const { response } = await client().resendSmsMfa({}, { meta: signInMeta() });
   return response;
 }
 
@@ -181,7 +218,7 @@ export async function verifyRecoveryCode(
 ): Promise<MfaVerifyResult> {
   const { response } = await client().verifyRecoveryCode(
     { code },
-    { meta: authMeta() },
+    { meta: signInMeta() },
   );
   return mfaVerified(response);
 }
@@ -264,11 +301,12 @@ export type PasskeySignInResult = WithId<
   WebAuthnAuthenticationFinishResponse,
   "sessionId",
   SessionId
->;
+> & { pending: PendingSignIn | null };
 
 /**
  * Finish a passkey sign-in with the assertion; the server finds the ceremony
- * by the challenge the assertion signs.
+ * by the challenge the assertion signs. `pending` is the second factor the
+ * sign-in still owes, kept for its completion.
  */
 export async function webAuthnAuthenticationFinish(
   credential: Uint8Array,
@@ -278,7 +316,11 @@ export async function webAuthnAuthenticationFinish(
     { credential, principal: principal ?? "" },
     { meta: authMeta() },
   );
-  return { ...response, sessionId: required(SessionId, response.sessionId) };
+  return {
+    ...response,
+    sessionId: required(SessionId, response.sessionId),
+    pending: holdPendingSignIn(response),
+  };
 }
 
 export async function webAuthnRegistrationStart(
@@ -425,19 +467,26 @@ export async function confirmIdpLink(
 
 // ── Organization Selector ──
 
-export async function listUserOrganizations(): Promise<ListUserOrganizationsResponse> {
+/** An organization the sign-in may continue in, named by its typed id. */
+export type UserOrganizationRef = WithId<UserOrganization, "id", OrgId>;
+
+/** The organizations the signed-in user may continue in. */
+export async function listUserOrganizations(): Promise<UserOrganizationRef[]> {
   const { response } = await client().listUserOrganizations(
     {},
     { meta: authMeta() },
   );
-  return response;
+  return response.organizations.map((organization) => ({
+    ...organization,
+    id: required(OrgId, organization.id),
+  }));
 }
 
 export async function selectOrganization(
-  organizationId: string,
+  organizationId: OrgId,
 ): Promise<SelectOrganizationResponse> {
   const { response } = await client().selectOrganization(
-    { organizationId },
+    { organizationId: organizationId.toWire() },
     { meta: authMeta() },
   );
   return response;
@@ -848,9 +897,13 @@ export type LoginFinishResult = WithId<
   OpaqueLoginFinishResponse,
   "sessionId",
   SessionId
->;
+> & { pending: PendingSignIn | null };
 
-/** Finish the login `loginId` (from its start) with the client's KE3. */
+/**
+ * Finish the login `loginId` (from its start) with the client's KE3.
+ * `pending` is the second factor the sign-in still owes, kept for its
+ * completion.
+ */
 export async function opaqueLoginFinish(
   principal: string,
   credentialFinalization: Uint8Array,
@@ -861,7 +914,11 @@ export async function opaqueLoginFinish(
     credentialFinalization,
     loginId: loginId.toWire(),
   });
-  return { ...response, sessionId: required(SessionId, response.sessionId) };
+  return {
+    ...response,
+    sessionId: required(SessionId, response.sessionId),
+    pending: holdPendingSignIn(response),
+  };
 }
 
 // Re-export types for convenience

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

@@ -2,7 +2,12 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { setActivePinia, createPinia } from "pinia";
 import { createApp, defineComponent } from "vue";
 import { createRouter, createMemoryHistory } from "vue-router";
-import { authorizationContinuation, useLoginSuccess } from "./useLoginSuccess";
+import { StepUpMethod } from "@structured-id/proto/sid/v1/authn/auth";
+import {
+  SECOND_FACTOR_PATH,
+  authorizationContinuation,
+  useLoginSuccess,
+} from "./useLoginSuccess";
 import { useAuthStore } from "../../stores/auth";
 
 // Mock checkBffSession from BFF composable
@@ -26,6 +31,7 @@ async function withApp<T>(
       { path: "/login", component: { template: "<div />" } },
       { path: "/account", component: { template: "<div />" } },
       { path: "/admin", component: { template: "<div />" } },
+      { path: SECOND_FACTOR_PATH, component: { template: "<div />" } },
     ],
   });
   await router.push(at);
@@ -190,6 +196,27 @@ describe("useLoginSuccess (BFF cookie mode)", () => {
     expect(router.currentRoute.value.path).toBe("/account");
   });
 
+  // Regression: a sign-in that still owes its second factor went into the
+  // app (or back to the authorization request) as if signed in. It goes to
+  // the second-factor page instead, carrying the request it waits for, and
+  // reads no app session.
+  it("continues a sign-in owing its second factor to the factor's page", async () => {
+    const leaveTo = vi.fn();
+    const { result, router } = await withApp(
+      () => useLoginSuccess("/account", { issuerOrigin: ISSUER, leaveTo }),
+      `/login?rd=${encodeURIComponent(CONTINUATION)}`,
+    );
+
+    await result.onLoginSuccess({
+      pending: { secondFactors: [StepUpMethod.TOTP], enrollableFactors: [] },
+    });
+
+    expect(router.currentRoute.value.path).toBe(SECOND_FACTOR_PATH);
+    expect(router.currentRoute.value.query.rd).toBe(CONTINUATION);
+    expect(leaveTo).not.toHaveBeenCalled();
+    expect(mockCheckBffSession).not.toHaveBeenCalled();
+  });
+
   it("navigates when BFF session returns null (cookie not yet set)", async () => {
     mockCheckBffSession.mockResolvedValue(null);
 

package/src/profile/composables/useLoginSuccess.ts

@@ -14,13 +14,24 @@ import type { SessionId } from "@structured-id/ids";
 import { useRouter } from "vue-router";
 import { useAuthStore } from "../../index";
 import { checkBffSession } from "../../index";
+import type { PendingSignIn } from "../pendingSignIn";
 
 export interface LoginSuccessResult {
   sessionId?: SessionId;
+  /** The second factor the sign-in still owes; absent or null when complete. */
+  pending?: PendingSignIn | null;
 }
 
+/**
+ * The app's page that completes a sign-in owing its second factor, reading
+ * what it owes from `pendingSignIn()`.
+ */
+export const SECOND_FACTOR_PATH = "/account/login/mfa";
+
 /** Options of {@link useLoginSuccess}. */
 export interface LoginSuccessOptions {
+  /** The app's second-factor page; {@link SECOND_FACTOR_PATH} by default. */
+  secondFactorPath?: string;
   /**
    * Origin of the SID installation whose issuers may send users to this
    * sign-in page (e.g. `https://sid.example.com`). Without it, `rd` is never
@@ -96,7 +107,17 @@ export function useLoginSuccess(
   const auth = useAuthStore();
   const router = useRouter();
 
-  async function onLoginSuccess(_result?: LoginSuccessResult) {
+  async function onLoginSuccess(result?: LoginSuccessResult) {
+    if (result?.pending) {
+      // Not signed in yet: the second factor completes the sign-in, and the
+      // authorization request it waits for goes along.
+      const rd = router.currentRoute.value.query.rd;
+      await router.push({
+        path: options.secondFactorPath ?? SECOND_FACTOR_PATH,
+        query: typeof rd === "string" ? { rd } : {},
+      });
+      return;
+    }
     const back = options.issuerOrigin
       ? authorizationContinuation(
           router.currentRoute.value.query.rd,

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

@@ -9,18 +9,24 @@ import {
   useUpstreamCallback,
   type UpstreamApi,
   type UpstreamBrowser,
+  type UpstreamOutcome,
 } from "./useUpstreamSignIn";
 import { UPSTREAM_CALLBACK_PATH, peekUpstream } from "../upstream";
+import { SECOND_FACTOR_PATH } from "./useLoginSuccess";
+import { endPendingSignIn, holdPendingSignIn } from "../pendingSignIn";
+import { StepUpMethod } from "@structured-id/proto/sid/v1/authn/auth";
+import { UpstreamProviderId } from "@structured-id/ids";
 
 vi.mock("../../composables/useBffAuth", () => ({
   checkBffSession: vi.fn().mockResolvedValue(null),
 }));
 
+const P1 = UpstreamProviderId.parse("0192f3a4-7c1e-7b2a-9d4e-3f5a6b7c8d20");
 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") {
+function api(outcome: UpstreamOutcome = "signed-in") {
   return {
     list: vi.fn().mockResolvedValue([]),
     initiate: vi.fn().mockResolvedValue({
@@ -43,7 +49,10 @@ function browser(): UpstreamBrowser & { left: string[] } {
   };
 }
 
-beforeEach(() => sessionStorage.clear());
+beforeEach(() => {
+  endPendingSignIn();
+  sessionStorage.clear();
+});
 
 describe("startUpstream", () => {
   // The issuer starts the sign-in for this origin's exact callback page; the
@@ -51,18 +60,17 @@ describe("startUpstream", () => {
   it("starts at the issuer and leaves for the provider", async () => {
     const calls = api();
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     expect(calls.initiate).toHaveBeenCalledWith(
-      "p1",
+      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,
-    });
+    const kept = peekUpstream(sessionStorage, "s1");
+    expect(kept?.provider.toString()).toBe(P1.toString());
+    expect(kept?.rd).toBe(RD);
   });
 
   // A refused start keeps nothing and leaves nowhere.
@@ -70,9 +78,7 @@ describe("startUpstream", () => {
     const calls = api();
     calls.initiate.mockRejectedValue(new Error("refused"));
     const page = browser();
-    await expect(startUpstream("p1", RD, calls, page)).rejects.toThrow(
-      "refused",
-    );
+    await expect(startUpstream(P1, RD, calls, page)).rejects.toThrow("refused");
     expect(page.left).toEqual([]);
     expect(sessionStorage.length).toBe(0);
   });
@@ -84,7 +90,7 @@ describe("abandonUpstream", () => {
   // nothing is left behind.
   it("takes the kept request of a refused return", async () => {
     const page = browser();
-    await startUpstream("p1", RD, api(), page);
+    await startUpstream(P1, RD, api(), page);
     expect(abandonUpstream("s1", page)).toBe(RD);
     expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
     expect(abandonUpstream("s1", page)).toBeNull();
@@ -97,10 +103,12 @@ describe("completeUpstream", () => {
   it("completes the sign-in this tab started", async () => {
     const calls = api();
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     const done = await completeUpstream("c1", "s1", calls, page);
+    // The provider the return completes at is the one the start kept.
+    expect(calls.complete.mock.calls[0][0].toString()).toBe(P1.toString());
     expect(calls.complete).toHaveBeenCalledWith(
-      "p1",
+      expect.any(UpstreamProviderId),
       "c1",
       "s1",
       `${ORIGIN}${UPSTREAM_CALLBACK_PATH}`,
@@ -116,7 +124,7 @@ describe("completeUpstream", () => {
     expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
       outcome: "unknown",
     });
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     await completeUpstream("c1", "s1", calls, page);
     expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
       outcome: "unknown",
@@ -128,7 +136,7 @@ describe("completeUpstream", () => {
   it("reports an account that needs linking", async () => {
     const calls = api("linking-required");
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     expect(await completeUpstream("c1", "s1", calls, page)).toEqual({
       outcome: "linking-required",
       rd: RD,
@@ -147,6 +155,7 @@ async function callbackAt(
     routes: [
       { path: UPSTREAM_CALLBACK_PATH, component: { template: "<div />" } },
       { path: "/account", component: { template: "<div />" } },
+      { path: SECOND_FACTOR_PATH, component: { template: "<div />" } },
     ],
   });
   await router.push(at);
@@ -179,7 +188,7 @@ describe("useUpstreamCallback", () => {
   it("continues the request kept for the state", async () => {
     const calls = api();
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     const { result, left } = await callbackAt(
       `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
       calls,
@@ -195,7 +204,7 @@ describe("useUpstreamCallback", () => {
   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);
+    await startUpstream(P1, null, calls, page);
     const { result, router, left } = await callbackAt(
       `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1&rd=${encodeURIComponent(RD)}`,
       calls,
@@ -211,7 +220,7 @@ describe("useUpstreamCallback", () => {
   it("answers a provider error with the waiting request", async () => {
     const calls = api();
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     const { result } = await callbackAt(
       `${UPSTREAM_CALLBACK_PATH}?error=access_denied&state=s1`,
       calls,
@@ -230,7 +239,7 @@ describe("useUpstreamCallback", () => {
     const calls = api();
     calls.complete.mockRejectedValue(new Error("unavailable"));
     const page = browser();
-    await startUpstream("p1", RD, calls, page);
+    await startUpstream(P1, RD, calls, page);
     const { result, left } = await callbackAt(
       `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
       calls,
@@ -257,11 +266,35 @@ describe("useUpstreamCallback", () => {
     expect(left).toEqual([]);
   });
 
+  // Regression: a provider sign-in of an account owing its second factor
+  // was reported signed in and continued to the request. It goes to the
+  // second-factor page with the request it waits for.
+  it("continues a sign-in owing its second factor to the factor's page", async () => {
+    const calls = api("second-factor");
+    holdPendingSignIn({
+      secondFactors: [StepUpMethod.TOTP],
+      enrollableFactors: [],
+      browserCsrf: "csrf-1",
+    });
+    const page = browser();
+    await startUpstream(P1, RD, calls, page);
+    const { result, router, left } = await callbackAt(
+      `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
+      calls,
+      page,
+    );
+    await result.complete();
+    expect(result.failure.value).toBeNull();
+    expect(left).toEqual([]);
+    expect(router.currentRoute.value.path).toBe(SECOND_FACTOR_PATH);
+    expect(router.currentRoute.value.query.rd).toBe(RD);
+  });
+
   // 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);
+    await startUpstream(P1, RD, calls, page);
     const { result, left } = await callbackAt(
       `${UPSTREAM_CALLBACK_PATH}?code=c1&state=s1`,
       calls,

package/src/profile/composables/useUpstreamSignIn.ts

@@ -3,8 +3,9 @@
  * 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 { ref, shallowRef } from "vue";
 import { useRoute, useRouter } from "vue-router";
+import { UpstreamProviderId, required } from "@structured-id/ids";
 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";
@@ -15,51 +16,70 @@ import {
   upstreamCallbackUri,
 } from "../upstream";
 import { useLoginSuccess, type LoginSuccessOptions } from "./useLoginSuccess";
+import { holdPendingSignIn, pendingSignIn } from "../pendingSignIn";
 
 export type { EnabledProviderInfo };
 
+/** A provider the issuer trusts, named by its typed id. */
+export type UpstreamProvider = Omit<EnabledProviderInfo, "id"> & {
+  id: UpstreamProviderId;
+};
+
 /** The calls a sign-in makes; the issuer's upstream service by default. */
 export interface UpstreamApi {
-  list(): Promise<EnabledProviderInfo[]>;
+  list(): Promise<UpstreamProvider[]>;
   initiate(
-    provider: string,
+    provider: UpstreamProviderId,
     redirectUri: string,
   ): Promise<{ authorizationUrl: string; stateToken: string }>;
   complete(
-    provider: string,
+    provider: UpstreamProviderId,
     code: string,
     state: string,
     redirectUri: string,
-  ): Promise<"signed-in" | "linking-required">;
+  ): Promise<UpstreamOutcome>;
 }
 
+/**
+ * What the issuer answered a completed return: signed in, signed in but
+ * owing a second factor (kept as the tab's pending sign-in), or no Profile
+ * linked to the upstream account.
+ */
+export type UpstreamOutcome =
+  "signed-in" | "second-factor" | "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,
-      );
+      return response.providers
+        .map((provider) => ({
+          ...provider,
+          id: required(UpstreamProviderId, provider.id),
+        }))
+        .sort((a, b) => a.displayOrder - b.displayOrder);
     },
     async initiate(provider, redirectUri) {
       const { response } = await client().initiateUpstreamAuth({
-        providerId: provider,
+        providerId: provider.toWire(),
         redirectUri,
       });
       return response;
     },
     async complete(provider, code, state, redirectUri) {
       const { response } = await client().handleUpstreamCallback({
-        providerId: provider,
+        providerId: provider.toWire(),
         code,
         state,
         redirectUri,
       });
       switch (response.result.oneofKind) {
         case "success":
-          return "signed-in";
+          return holdPendingSignIn(response.result.success)
+            ? "second-factor"
+            : "signed-in";
         case "linkingRequired":
           return "linking-required";
         default:
@@ -95,7 +115,7 @@ export function pageBrowser(
  * starts the sign-in for this origin's callback page.
  */
 export async function startUpstream(
-  provider: string,
+  provider: UpstreamProviderId,
   rd: string | null,
   api: UpstreamApi = upstreamApi(),
   browser: UpstreamBrowser = pageBrowser(),
@@ -124,7 +144,7 @@ export function abandonUpstream(
 export type UpstreamReturn =
   | {
       /** `failed`: the issuer could not complete it. */
-      outcome: "signed-in" | "linking-required" | "failed";
+      outcome: UpstreamOutcome | "failed";
       rd: string | null;
     }
   | { outcome: "unknown" };
@@ -170,7 +190,10 @@ export function useUpstreamSignIn(
   rd: () => string | null,
   options: UpstreamSignInOptions = {},
 ) {
-  const providers = ref<EnabledProviderInfo[]>([]);
+  // Shallow: a typed id keeps its bytes in private fields, which a deep
+  // reactive proxy cannot read.
+  const providers = shallowRef<UpstreamProvider[]>([]);
+  /** The text form of the provider the sign-in is leaving for. */
   const loading = ref<string | null>(null);
   const error = ref<string | null>(null);
   const api = () => options.api ?? upstreamApi();
@@ -184,8 +207,8 @@ export function useUpstreamSignIn(
     }
   }
 
-  async function signInWith(provider: string) {
-    loading.value = provider;
+  async function signInWith(provider: UpstreamProviderId) {
+    loading.value = provider.toString();
     error.value = null;
     try {
       await startUpstream(
@@ -262,7 +285,7 @@ export function useUpstreamCallback(
         return;
       }
       continued.value = done.rd;
-      if (done.outcome !== "signed-in") {
+      if (done.outcome === "linking-required" || done.outcome === "failed") {
         failure.value = done.outcome;
         return;
       }
@@ -270,7 +293,10 @@ export function useUpstreamCallback(
         path: route.path,
         query: done.rd ? { rd: done.rd } : {},
       });
-      await onLoginSuccess();
+      // A sign-in owing its second factor continues to the factor's page.
+      await onLoginSuccess(
+        done.outcome === "second-factor" ? { pending: pendingSignIn() } : {},
+      );
     } catch {
       failure.value = "failed";
     }

package/src/profile/index.ts

@@ -17,5 +17,8 @@ export * from "./components";
 // Upstream identity provider sign-in: what a return keeps
 export * from "./upstream";
 
+// A browser sign-in owing its second factor
+export * from "./pendingSignIn";
+
 // Auth helper
 export { authMeta } from "./auth";

package/src/profile/pendingSignIn.test.ts

@@ -0,0 +1,126 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { StepUpMethod } from "@structured-id/proto/sid/v1/authn/auth";
+import {
+  endPendingSignIn,
+  holdPendingSignIn,
+  pendingSignIn,
+  pendingSignInMeta,
+} from "./pendingSignIn";
+
+const owing = {
+  secondFactors: [StepUpMethod.TOTP],
+  enrollableFactors: [],
+  browserCsrf: "csrf-1",
+};
+
+beforeEach(() => {
+  endPendingSignIn();
+  sessionStorage.clear();
+});
+
+describe("pending sign-in", () => {
+  // A sign-in owing its second factor is kept with the CSRF token its
+  // completion sends; the token is not part of what pages read.
+  it("keeps a sign-in that owes a factor", () => {
+    expect(holdPendingSignIn(owing)).toEqual({
+      secondFactors: [StepUpMethod.TOTP],
+      enrollableFactors: [],
+    });
+    expect(pendingSignIn()).toEqual({
+      secondFactors: [StepUpMethod.TOTP],
+      enrollableFactors: [],
+    });
+    expect(pendingSignInMeta()).toEqual({ "x-csrf-token": "csrf-1" });
+  });
+
+  // An account that must enroll its first factor is pending too.
+  it("keeps a sign-in that must enroll its first factor", () => {
+    holdPendingSignIn({
+      secondFactors: [],
+      enrollableFactors: [StepUpMethod.TOTP],
+      browserCsrf: "csrf-2",
+    });
+    expect(pendingSignIn()?.enrollableFactors).toEqual([StepUpMethod.TOTP]);
+    expect(pendingSignInMeta()).toEqual({ "x-csrf-token": "csrf-2" });
+  });
+
+  // A complete sign-in replaces an earlier pending one: the earlier token
+  // is never sent with the new session.
+  it("forgets an earlier pending sign-in when a sign-in completes", () => {
+    holdPendingSignIn(owing);
+    expect(
+      holdPendingSignIn({ secondFactors: [], enrollableFactors: [] }),
+    ).toBeNull();
+    expect(pendingSignIn()).toBeNull();
+    expect(pendingSignInMeta()).toEqual({});
+  });
+
+  // Without its CSRF token the browser cannot complete the context; the
+  // answer is refused loudly rather than kept unusable.
+  it("refuses a pending answer without its CSRF token", () => {
+    expect(() =>
+      holdPendingSignIn({ ...owing, browserCsrf: undefined }),
+    ).toThrow();
+    expect(pendingSignIn()).toBeNull();
+  });
+
+  it("ends the pending sign-in", () => {
+    holdPendingSignIn(owing);
+    endPendingSignIn();
+    expect(pendingSignIn()).toBeNull();
+    expect(pendingSignInMeta()).toEqual({});
+  });
+
+  // Regression: with tab storage denied by browser policy, reading
+  // `sessionStorage` threw, so even a complete sign-in failed. A complete
+  // sign-in needs no storage, and a pending one is still held for the
+  // completion this page load sends.
+  it("works without tab storage", () => {
+    const denied = Object.getOwnPropertyDescriptor(window, "sessionStorage");
+    Object.defineProperty(window, "sessionStorage", {
+      configurable: true,
+      get() {
+        throw new DOMException("denied", "SecurityError");
+      },
+    });
+    try {
+      expect(
+        holdPendingSignIn({ secondFactors: [], enrollableFactors: [] }),
+      ).toBeNull();
+      holdPendingSignIn(owing);
+      expect(pendingSignIn()?.secondFactors).toEqual([StepUpMethod.TOTP]);
+      expect(pendingSignInMeta()).toEqual({ "x-csrf-token": "csrf-1" });
+      endPendingSignIn();
+      expect(pendingSignIn()).toBeNull();
+    } finally {
+      Object.defineProperty(window, "sessionStorage", denied!);
+    }
+  });
+
+  // A reload completes the sign-in from the tab's copy of the record.
+  it("is completed after a reload from the tab's copy", async () => {
+    holdPendingSignIn(owing);
+    const reloaded = await freshLoad();
+    expect(reloaded.pendingSignIn()?.secondFactors).toEqual([
+      StepUpMethod.TOTP,
+    ]);
+    expect(reloaded.pendingSignInMeta()).toEqual({ "x-csrf-token": "csrf-1" });
+  });
+
+  // A copy the reloaded page cannot read is no pending sign-in.
+  it("reads a corrupt copy as none", async () => {
+    sessionStorage.setItem("sid.pending-sign-in", "{not json");
+    expect((await freshLoad()).pendingSignIn()).toBeNull();
+    sessionStorage.setItem(
+      "sid.pending-sign-in",
+      JSON.stringify({ csrf: 1, secondFactors: [], enrollableFactors: [] }),
+    );
+    expect((await freshLoad()).pendingSignIn()).toBeNull();
+  });
+});
+
+/** The module as a new page load finds it: nothing held, only the tab's copy. */
+async function freshLoad(): Promise<typeof import("./pendingSignIn")> {
+  vi.resetModules();
+  return import("./pendingSignIn");
+}

package/src/profile/pendingSignIn.ts

@@ -0,0 +1,140 @@
+/**
+ * A browser sign-in that still owes its second factor. The first factor's
+ * answer names the factors that complete it, the factors it may enroll
+ * first, and the CSRF token the browser sends with its pending cookie to
+ * complete it. The record is kept until the completion ends it: a completion
+ * whose outcome is unknown is repeated with the same token and receives the
+ * sign-in it delivered.
+ *
+ * The page holds the record itself; the tab's session storage keeps a copy
+ * so a reload can still complete it. Storage the browser denies only loses
+ * that copy: a complete sign-in never needs it.
+ */
+import { StepUpMethod } from "@structured-id/proto/sid/v1/authn/auth";
+
+/** What a first-factor answer states about the sign-in it delivered. */
+export interface FirstFactorAnswer {
+  secondFactors: StepUpMethod[];
+  enrollableFactors: StepUpMethod[];
+  browserCsrf?: string;
+}
+
+/** A sign-in owing its second factor. */
+export interface PendingSignIn {
+  /** The enrolled factors that complete it; empty when it must enroll one first. */
+  secondFactors: StepUpMethod[];
+  /** The factors it may enroll first, when the account has none. */
+  enrollableFactors: StepUpMethod[];
+}
+
+interface Kept extends PendingSignIn {
+  csrf: string;
+}
+
+const KEY = "sid.pending-sign-in";
+
+/** The CSRF header the sign-in surface checks with the pending cookie. */
+const CSRF_HEADER = "x-csrf-token";
+
+/** The record this page load holds; `undefined` until it read the tab's copy. */
+let held: Kept | null | undefined;
+
+/** The tab's session storage, or null where the browser denies it. */
+function tabStorage(): Storage | null {
+  try {
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function methods(value: unknown): StepUpMethod[] | null {
+  return Array.isArray(value) && value.every((m) => typeof m === "number")
+    ? (value as StepUpMethod[])
+    : null;
+}
+
+/** The tab's copy, none when it is absent, unreadable or not this module's. */
+function stored(): Kept | null {
+  try {
+    const raw = tabStorage()?.getItem(KEY);
+    if (!raw) return null;
+    const kept = JSON.parse(raw) as Record<string, unknown>;
+    const secondFactors = methods(kept.secondFactors);
+    const enrollableFactors = methods(kept.enrollableFactors);
+    if (typeof kept.csrf !== "string" || !secondFactors || !enrollableFactors) {
+      return null;
+    }
+    return { csrf: kept.csrf, secondFactors, enrollableFactors };
+  } catch {
+    return null;
+  }
+}
+
+/** Keep `kept` as the record, its copy in the tab when the tab allows. */
+function keep(kept: Kept | null): void {
+  held = kept;
+  try {
+    const storage = tabStorage();
+    if (kept) storage?.setItem(KEY, JSON.stringify(kept));
+    else storage?.removeItem(KEY);
+  } catch {
+    // Without the copy a reload no longer completes the sign-in; this page
+    // load still does.
+  }
+}
+
+function current(): Kept | null {
+  if (held === undefined) held = stored();
+  return held;
+}
+
+/**
+ * Keep the sign-in `answer` delivered when it still owes a factor; null when
+ * the sign-in is complete. A new first factor replaces any earlier record.
+ */
+export function holdPendingSignIn(
+  answer: FirstFactorAnswer,
+): PendingSignIn | null {
+  keep(null);
+  const owed =
+    answer.secondFactors.length > 0 || answer.enrollableFactors.length > 0;
+  if (!owed) return null;
+  if (!answer.browserCsrf) {
+    throw new Error(
+      "The issuer answered a pending sign-in without its CSRF token",
+    );
+  }
+  const kept: Kept = {
+    csrf: answer.browserCsrf,
+    secondFactors: [...answer.secondFactors],
+    enrollableFactors: [...answer.enrollableFactors],
+  };
+  keep(kept);
+  return {
+    secondFactors: kept.secondFactors,
+    enrollableFactors: kept.enrollableFactors,
+  };
+}
+
+/** The sign-in this tab is completing, if any. */
+export function pendingSignIn(): PendingSignIn | null {
+  const kept = current();
+  return kept
+    ? {
+        secondFactors: kept.secondFactors,
+        enrollableFactors: kept.enrollableFactors,
+      }
+    : null;
+}
+
+/** The metadata a completion of the pending sign-in sends; empty without one. */
+export function pendingSignInMeta(): Record<string, string> {
+  const kept = current();
+  return kept ? { [CSRF_HEADER]: kept.csrf } : {};
+}
+
+/** End the pending sign-in: its completion delivered the session, or it ended. */
+export function endPendingSignIn(): void {
+  keep(null);
+}

package/src/profile/upstream.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
+import { UpstreamProviderId } from "@structured-id/ids";
 import {
   UPSTREAM_CALLBACK_PATH,
   peekUpstream,
@@ -8,6 +9,7 @@ import {
   upstreamRequestOfPage,
 } from "./upstream";
 
+const P1 = UpstreamProviderId.parse("0192f3a4-7c1e-7b2a-9d4e-3f5a6b7c8d20");
 const RD =
   "https://sid.example.com/i/0123456789abcdef0123456789abcdef/oauth2/authorize?client_id=ops&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Ar";
 
@@ -35,25 +37,26 @@ 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,
-    });
+    rememberUpstream(sessionStorage, "s1", { provider: P1, rd: RD });
+    const kept = peekUpstream(sessionStorage, "s1");
+    expect(kept?.provider.toString()).toBe(P1.toString());
+    expect(kept?.rd).toBe(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 });
+    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");
+    rememberUpstream(sessionStorage, "s1", { provider: P1, rd: RD });
+    expect(takeUpstream(sessionStorage, "s1")?.provider.toString()).toBe(
+      P1.toString(),
+    );
     expect(takeUpstream(sessionStorage, "s1")).toBeUndefined();
   });
 
@@ -61,8 +64,13 @@ describe("the kept return", () => {
   it("ignores what it did not write", () => {
     sessionStorage.setItem("sid.upstream.s1", "not json");
     sessionStorage.setItem("sid.upstream.s2", JSON.stringify({ rd: RD }));
+    sessionStorage.setItem(
+      "sid.upstream.s3",
+      JSON.stringify({ provider: "not-an-id", rd: RD }),
+    );
     expect(peekUpstream(sessionStorage, "s1")).toBeUndefined();
     expect(peekUpstream(sessionStorage, "s2")).toBeUndefined();
+    expect(peekUpstream(sessionStorage, "s3")).toBeUndefined();
   });
 });
 
@@ -84,7 +92,7 @@ describe("upstreamRequestOfPage", () => {
   // 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 });
+    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();
@@ -106,7 +114,7 @@ describe("upstreamRequestOfPage", () => {
 
   // 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 });
+    rememberUpstream(sessionStorage, "s1", { provider: P1, rd: RD });
     expect(
       upstreamRequestOfPage(
         location("/upstream/return?state=s1"),

package/src/profile/upstream.ts

@@ -9,6 +9,7 @@
  * The kept entry is no credential: the issuer keeps the request's state,
  * PKCE verifier and nonce itself and checks `state` on completion.
  */
+import { UpstreamProviderId } from "@structured-id/ids";
 
 /** Where the provider returns the browser, unless the app names its own. */
 export const UPSTREAM_CALLBACK_PATH = "/account/upstream/callback";
@@ -27,20 +28,23 @@ export function upstreamCallbackUri(
 /** What the return to the callback page needs. */
 export interface PendingUpstream {
   /** The provider the sign-in started at. */
-  provider: string;
+  provider: UpstreamProviderId;
   /** 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`. */
+/** Keep `pending` for the return carrying `state`; the provider by its text form. */
 export function rememberUpstream(
   storage: Storage,
   state: string,
   pending: PendingUpstream,
 ): void {
-  storage.setItem(PREFIX + state, JSON.stringify(pending));
+  storage.setItem(
+    PREFIX + state,
+    JSON.stringify({ provider: pending.provider.toString(), rd: pending.rd }),
+  );
 }
 
 /** What was kept for `state`, left in place; `undefined` when nothing is. */
@@ -51,12 +55,11 @@ export function peekUpstream(
   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;
-    }
+    const parsed = JSON.parse(kept) as { provider?: unknown; rd?: unknown };
+    if (typeof parsed.provider !== "string") return undefined;
     return {
-      provider: parsed.provider,
+      // An entry whose provider is no identifier was not kept by this code.
+      provider: UpstreamProviderId.parse(parsed.provider),
       rd: typeof parsed.rd === "string" ? parsed.rd : null,
     };
   } catch {