@hraness/suite-accounts 0.9.20

package/src/browser-session.ts

@@ -0,0 +1,260 @@
+import {
+  SUITE_OIDC_JUST_SIGNED_IN_STORAGE_KEY,
+} from "./oidc-continuation.js";
+
+const MAXIMUM_SESSION_RESPONSE_BYTES = 32_768;
+const SESSION_PATH = "/api/suite-auth/session";
+const REFRESH_PATH = "/api/suite-auth/refresh";
+const SIGN_OUT_PATH = "/api/suite-auth/sign-out";
+
+export const SUITE_OIDC_REFRESH_LOCK_NAME =
+  "jungle-suite-accounts:oidc-refresh:v1";
+export const SUITE_OIDC_SESSION_CHANNEL_NAME =
+  "jungle-suite-accounts:oidc-session:v1";
+
+const SIGNED_OUT_EVENT = Object.freeze({
+  kind: "signed_out",
+  version: "suite-oidc-session-event-v1",
+});
+
+type SuiteOidcFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type SuiteOidcExclusiveLock = (
+  name: string,
+  task: () => Promise<unknown>,
+) => Promise<unknown>;
+
+export type SuiteOidcBrowserSessionDependencies = Readonly<{
+  fetch?: SuiteOidcFetch;
+  withExclusiveLock?: SuiteOidcExclusiveLock | null;
+}>;
+
+export type SuiteOidcBrowserSignOutDependencies =
+  SuiteOidcBrowserSessionDependencies & Readonly<{
+    notifySignedOut?: () => void;
+  }>;
+
+let localRefresh: Promise<unknown> | null = null;
+
+function isExactRefreshRequired(value: unknown): boolean {
+  return typeof value === "object"
+    && value !== null
+    && !Array.isArray(value)
+    && Object.keys(value).length === 1
+    && Reflect.get(value, "kind") === "refresh_required";
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  const contentType = response.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (contentType !== "application/json" || response.body === null) {
+    throw new Error("The suite session response was not JSON.");
+  }
+
+  const declaredLength = response.headers.get("content-length");
+  if (
+    declaredLength !== null
+    && (
+      !/^(?:0|[1-9]\d*)$/u.test(declaredLength)
+      || Number(declaredLength) > MAXIMUM_SESSION_RESPONSE_BYTES
+    )
+  ) {
+    await response.body.cancel().catch(() => undefined);
+    throw new Error("The suite session response was too large.");
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      total += result.value.byteLength;
+      if (total > MAXIMUM_SESSION_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new Error("The suite session response was too large.");
+      }
+      chunks.push(result.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  ) as unknown;
+}
+
+async function requestJson(
+  fetcher: SuiteOidcFetch,
+  path: typeof REFRESH_PATH | typeof SESSION_PATH | typeof SIGN_OUT_PATH,
+  method: "GET" | "POST",
+): Promise<unknown> {
+  const response = await fetcher(path, {
+    cache: "no-store",
+    credentials: "same-origin",
+    headers: { accept: "application/json" },
+    method,
+    redirect: "error",
+  });
+  const value = await readBoundedJson(response);
+  if (!response.ok) {
+    throw new Error("The suite session request failed.");
+  }
+  return value;
+}
+
+function exactSignedOut(value: unknown): boolean {
+  return typeof value === "object"
+    && value !== null
+    && !Array.isArray(value)
+    && Object.keys(value).length === 1
+    && Reflect.get(value, "kind") === "signed_out";
+}
+
+/** Notify every open tab on this exact product origin that custody ended. */
+export function broadcastSuiteOidcBrowserSignOut(): void {
+  if (typeof BroadcastChannel === "undefined") return;
+  const channel = new BroadcastChannel(SUITE_OIDC_SESSION_CHANNEL_NAME);
+  try {
+    channel.postMessage(SIGNED_OUT_EVENT);
+  } finally {
+    channel.close();
+  }
+}
+
+/** Subscribe to the bounded cross-tab suite-session event. */
+export function subscribeSuiteOidcBrowserSignOut(
+  listener: () => void,
+): () => void {
+  if (typeof BroadcastChannel === "undefined") return () => undefined;
+  const channel = new BroadcastChannel(SUITE_OIDC_SESSION_CHANNEL_NAME);
+  const onMessage = (event: MessageEvent<unknown>): void => {
+    const value = event.data;
+    if (
+      typeof value === "object"
+      && value !== null
+      && !Array.isArray(value)
+      && Object.keys(value).length === 2
+      && Reflect.get(value, "kind") === SIGNED_OUT_EVENT.kind
+      && Reflect.get(value, "version") === SIGNED_OUT_EVENT.version
+    ) {
+      listener();
+    }
+  };
+  channel.addEventListener("message", onMessage);
+  return () => {
+    channel.removeEventListener("message", onMessage);
+    channel.close();
+  };
+}
+
+async function withLocalRefreshLock(
+  task: () => Promise<unknown>,
+): Promise<unknown> {
+  if (localRefresh !== null) return await localRefresh;
+  const pending = task();
+  localRefresh = pending;
+  try {
+    return await pending;
+  } finally {
+    if (localRefresh === pending) localRefresh = null;
+  }
+}
+
+async function withRefreshLock(
+  task: () => Promise<unknown>,
+  injectedLock: SuiteOidcExclusiveLock | null | undefined,
+): Promise<unknown> {
+  if (injectedLock !== undefined) {
+    return injectedLock === null
+      ? await withLocalRefreshLock(task)
+      : await injectedLock(SUITE_OIDC_REFRESH_LOCK_NAME, task);
+  }
+  if (typeof navigator !== "undefined" && navigator.locks !== undefined) {
+    return await navigator.locks.request(
+      SUITE_OIDC_REFRESH_LOCK_NAME,
+      { mode: "exclusive" },
+      task,
+    );
+  }
+  return await withLocalRefreshLock(task);
+}
+
+/**
+ * Reads the product's same-origin suite session and refreshes it when needed.
+ *
+ * Web Locks serialize refresh-token rotation across tabs on the current
+ * product origin. The session is re-read after acquiring the lock so a waiter
+ * observes the cookie rotated by the preceding tab instead of replaying the
+ * old refresh token.
+ */
+export async function loadSuiteOidcBrowserSession(
+  dependencies: SuiteOidcBrowserSessionDependencies = {},
+): Promise<unknown> {
+  const fetcher = dependencies.fetch ?? globalThis.fetch;
+  const withExclusiveLock = dependencies.withExclusiveLock;
+  const current = await requestJson(fetcher, SESSION_PATH, "GET");
+  if (!isExactRefreshRequired(current)) return current;
+
+  return await withRefreshLock(async () => {
+    const latest = await requestJson(fetcher, SESSION_PATH, "GET");
+    return isExactRefreshRequired(latest)
+      ? await requestJson(fetcher, REFRESH_PATH, "POST")
+      : latest;
+  }, withExclusiveLock);
+}
+
+/**
+ * End the sealed relying-party session inside the same exclusive section used
+ * for refresh-token rotation, then notify sibling tabs only after the server
+ * confirms that local cookie custody ended.
+ */
+export async function signOutSuiteOidcBrowserSession(
+  dependencies: SuiteOidcBrowserSignOutDependencies = {},
+): Promise<void> {
+  const fetcher = dependencies.fetch ?? globalThis.fetch;
+  const notifySignedOut = dependencies.notifySignedOut
+    ?? broadcastSuiteOidcBrowserSignOut;
+  const withExclusiveLock = dependencies.withExclusiveLock;
+  await withRefreshLock(async () => {
+    const value = await requestJson(fetcher, SIGN_OUT_PATH, "POST");
+    if (!exactSignedOut(value)) {
+      throw new Error("The suite sign-out response was invalid.");
+    }
+  }, withExclusiveLock);
+  notifySignedOut();
+}
+
+/**
+ * Consume the one-shot marker the relying-party continuation page plants on
+ * this product origin immediately before its replace navigation. Returns true
+ * exactly once per completed sign-in so a product can show post-auth feedback.
+ */
+export function consumeSuiteOidcJustSignedIn(): boolean {
+  try {
+    if (
+      typeof sessionStorage === "undefined"
+      || sessionStorage.getItem(SUITE_OIDC_JUST_SIGNED_IN_STORAGE_KEY) === null
+    ) {
+      return false;
+    }
+    sessionStorage.removeItem(SUITE_OIDC_JUST_SIGNED_IN_STORAGE_KEY);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/client-configuration.ts

@@ -0,0 +1,172 @@
+import { err, isRecord, ok, type Result } from "@hraness/result";
+
+import { deepFreeze } from "./immutable.js";
+import {
+  getSuiteAccountsCurrentConsumerEnvironment,
+  getSuiteAccountsCurrentConsumer,
+  isSuiteAccountsCurrentConsumerId,
+  type SuiteAccountsAuthConfiguration,
+  type SuiteAccountsCurrentConsumerId,
+  type SuiteAccountsRemoteEnvironment,
+} from "./registry.js";
+import {
+  suiteAccountsCurrentOidcClientRegistration,
+  suiteAccountsOidcProviderConfiguration,
+  type SuiteAccountsOidcProviderConfiguration,
+} from "./urls.js";
+
+export const SUITE_ACCOUNTS_CLIENT_CONFIGURATION_VERSION =
+  "suite-accounts-client-configuration-v1" as const;
+export const SUITE_ACCOUNTS_WIRE_VERSION = "v1" as const;
+
+export type SuiteAccountsClientBinding = Readonly<{
+  authMode: SuiteAccountsAuthConfiguration["kind"];
+  callbackUrl: string | null;
+  clientId: string | null;
+  consumer: SuiteAccountsCurrentConsumerId;
+  environment: SuiteAccountsRemoteEnvironment;
+  origin: string;
+}>;
+
+export type SuiteAccountsClientConfiguration = Readonly<{
+  authBasePath: SuiteAccountsAuthConfiguration["basePath"];
+  binding: SuiteAccountsClientBinding;
+  configurationVersion: typeof SUITE_ACCOUNTS_CLIENT_CONFIGURATION_VERSION;
+  provider: SuiteAccountsOidcProviderConfiguration;
+  wireVersion: typeof SUITE_ACCOUNTS_WIRE_VERSION;
+}>;
+
+export type SuiteAccountsClientConfigurationIssue =
+  | "invalid-auth-mode"
+  | "invalid-binding"
+  | "invalid-callback-url"
+  | "invalid-client-id"
+  | "invalid-consumer"
+  | "invalid-environment"
+  | "invalid-origin";
+
+const BINDING_KEYS = [
+  "authMode",
+  "callbackUrl",
+  "clientId",
+  "consumer",
+  "environment",
+  "origin",
+] as const satisfies readonly (keyof SuiteAccountsClientBinding)[];
+
+type SuiteAccountsClientBindingInput = Readonly<{
+  [Key in (typeof BINDING_KEYS)[number]]: unknown;
+}>;
+
+function snapshotBinding(
+  input: unknown,
+): SuiteAccountsClientBindingInput | null {
+  if (!isRecord(input)) return null;
+
+  try {
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    const keys = Reflect.ownKeys(descriptors);
+    if (
+      keys.length !== BINDING_KEYS.length
+      || keys.some(key =>
+        typeof key !== "string"
+        || !(BINDING_KEYS as readonly string[]).includes(key)
+      )
+    ) {
+      return null;
+    }
+
+    for (const key of BINDING_KEYS) {
+      const descriptor = descriptors[key];
+      if (descriptor === undefined || !("value" in descriptor)) return null;
+    }
+
+    return {
+      authMode: descriptors.authMode!.value,
+      callbackUrl: descriptors.callbackUrl!.value,
+      clientId: descriptors.clientId!.value,
+      consumer: descriptors.consumer!.value,
+      environment: descriptors.environment!.value,
+      origin: descriptors.origin!.value,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function freezeConfiguration(
+  binding: SuiteAccountsClientBinding,
+  authBasePath: SuiteAccountsAuthConfiguration["basePath"],
+  provider: SuiteAccountsOidcProviderConfiguration,
+): SuiteAccountsClientConfiguration {
+  return deepFreeze({
+    authBasePath,
+    binding,
+    configurationVersion: SUITE_ACCOUNTS_CLIENT_CONFIGURATION_VERSION,
+    provider,
+    wireVersion: SUITE_ACCOUNTS_WIRE_VERSION,
+  });
+}
+
+/**
+ * Bind one client to an exact Accounts registration.
+ *
+ * The caller can state only its public binding. Issuer, JWKS, resource,
+ * endpoints, protocol version, and client-ID format come from the frozen
+ * Accounts registry and cannot be supplied or overridden.
+ */
+export function createSuiteAccountsClientConfiguration(
+  input: unknown,
+): Result<
+  SuiteAccountsClientConfiguration,
+  SuiteAccountsClientConfigurationIssue
+> {
+  const binding = snapshotBinding(input);
+  if (binding === null) return err("invalid-binding");
+  if (!isSuiteAccountsCurrentConsumerId(binding.consumer)) {
+    return err("invalid-consumer");
+  }
+  if (binding.environment !== "production") {
+    return err("invalid-environment");
+  }
+
+  const consumer = binding.consumer;
+  const environment = binding.environment;
+  const registration = getSuiteAccountsCurrentConsumer(consumer);
+  const deployed = getSuiteAccountsCurrentConsumerEnvironment(
+    consumer,
+    environment,
+  );
+  if (deployed === null || binding.origin !== deployed.siteUrl) {
+    return err("invalid-origin");
+  }
+  if (binding.authMode !== registration.auth.kind) {
+    return err("invalid-auth-mode");
+  }
+
+  const oauth = suiteAccountsCurrentOidcClientRegistration(
+    consumer,
+    environment,
+  );
+  const expectedClientId = oauth?.clientId ?? null;
+  const expectedCallbackUrl = oauth?.callbackUrl ?? null;
+  if (binding.clientId !== expectedClientId) {
+    return err("invalid-client-id");
+  }
+  if (binding.callbackUrl !== expectedCallbackUrl) {
+    return err("invalid-callback-url");
+  }
+
+  return ok(freezeConfiguration(
+    {
+      authMode: registration.auth.kind,
+      callbackUrl: expectedCallbackUrl,
+      clientId: expectedClientId,
+      consumer,
+      environment,
+      origin: deployed.siteUrl,
+    },
+    registration.auth.basePath,
+    suiteAccountsOidcProviderConfiguration(environment),
+  ));
+}

package/src/convex-browser-auth-browser.ts

@@ -0,0 +1,238 @@
+import {
+  loadSuiteOidcBrowserSession,
+  type SuiteOidcExclusiveLock,
+} from "./browser-session.js";
+import {
+  SUITE_CONVEX_BROWSER_PARENT_REFRESH_WINDOW_MS,
+  SUITE_CONVEX_BROWSER_TOKEN_PATH,
+} from "./convex-browser-auth.js";
+
+const MAXIMUM_TOKEN_RESPONSE_BYTES = 20 * 1_024;
+const TOKEN_RESPONSE_VERSION =
+  "suite-convex-browser-token-response-v1" as const;
+
+type FetchImplementation = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type SuiteConvexBrowserTokenLoaderDependencies = Readonly<{
+  fetch?: FetchImplementation;
+  now?: () => number;
+  refreshSuiteSession?: () => Promise<unknown>;
+  withExclusiveLock?: SuiteOidcExclusiveLock | null;
+}>;
+
+export type SuiteConvexBrowserTokenLoader = Readonly<{
+  clear(): void;
+  fetchAccessToken(): Promise<string | null>;
+}>;
+
+type TokenEndpointResult =
+  | Readonly<{ kind: "refresh_required" }>
+  | Readonly<{ kind: "signed_out" }>
+  | Readonly<{ expiresAtMs: number; kind: "token"; token: string }>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+): boolean {
+  const actual = Object.keys(value);
+  return actual.length === keys.length
+    && keys.every(key => Object.hasOwn(value, key));
+}
+
+function compactJwt(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length >= 32
+    && value.length <= 16_384
+    && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u.test(value);
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  const contentType = response.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  const cacheControl = response.headers.get("cache-control")?.toLowerCase();
+  if (
+    contentType !== "application/json"
+    || cacheControl === undefined
+    || !cacheControl.split(",").some(value => value.trim() === "no-store")
+    || response.body === null
+  ) {
+    throw new Error("The Convex token response was unsafe.");
+  }
+  const declaredLength = response.headers.get("content-length");
+  if (
+    declaredLength !== null
+    && (
+      !/^(?:0|[1-9]\d*)$/u.test(declaredLength)
+      || Number(declaredLength) > MAXIMUM_TOKEN_RESPONSE_BYTES
+    )
+  ) {
+    await response.body.cancel().catch(() => undefined);
+    throw new Error("The Convex token response was too large.");
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      length += result.value.byteLength;
+      if (length > MAXIMUM_TOKEN_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new Error("The Convex token response was too large.");
+      }
+      chunks.push(result.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  ) as unknown;
+}
+
+function parseEndpointResult(
+  value: unknown,
+  status: number,
+  nowMs: number,
+): TokenEndpointResult {
+  if (!isRecord(value)) {
+    throw new Error("The Convex token response was invalid.");
+  }
+  if (
+    status === 401
+    && exactKeys(value, ["kind"])
+    && value["kind"] === "signed_out"
+  ) {
+    return { kind: "signed_out" };
+  }
+  if (
+    status === 409
+    && exactKeys(value, ["kind"])
+    && value["kind"] === "refresh_required"
+  ) {
+    return { kind: "refresh_required" };
+  }
+  if (
+    status !== 200
+    || !exactKeys(value, ["expiresAtMs", "kind", "token", "version"])
+    || value["kind"] !== "token"
+    || value["version"] !== TOKEN_RESPONSE_VERSION
+    || !compactJwt(value["token"])
+    || typeof value["expiresAtMs"] !== "number"
+    || !Number.isSafeInteger(value["expiresAtMs"])
+    || value["expiresAtMs"] <= nowMs
+    || value["expiresAtMs"] > nowMs + 5 * 60_000
+  ) {
+    throw new Error("The Convex token response was invalid.");
+  }
+  return {
+    expiresAtMs: value["expiresAtMs"],
+    kind: "token",
+    token: value["token"],
+  };
+}
+
+async function requestToken(
+  fetcher: FetchImplementation,
+  now: () => number,
+): Promise<TokenEndpointResult> {
+  const response = await fetcher(SUITE_CONVEX_BROWSER_TOKEN_PATH, {
+    cache: "no-store",
+    credentials: "same-origin",
+    headers: { accept: "application/json" },
+    method: "POST",
+    redirect: "error",
+  });
+  return parseEndpointResult(
+    await readBoundedJson(response),
+    response.status,
+    now(),
+  );
+}
+
+/**
+ * Create a memory-only Convex bearer loader for `ConvexProviderWithAuth`.
+ *
+ * Concurrent calls share one in-flight exchange. A near-expiry parent session
+ * runs the existing origin-locked RP refresh path, then retries exactly once.
+ * No suite access or refresh token reaches this module or its return value.
+ */
+export function createSuiteConvexBrowserTokenLoader(
+  dependencies: SuiteConvexBrowserTokenLoaderDependencies = {},
+): SuiteConvexBrowserTokenLoader {
+  const fetcher = dependencies.fetch ?? globalThis.fetch;
+  const now = dependencies.now ?? Date.now;
+  const withExclusiveLock = dependencies.withExclusiveLock;
+  const refreshSuiteSession = dependencies.refreshSuiteSession
+    ?? (() => loadSuiteOidcBrowserSession({
+      fetch: fetcher,
+      ...(withExclusiveLock === undefined
+        ? {}
+        : { withExclusiveLock }),
+    }));
+  let cached: Readonly<{ expiresAtMs: number; token: string }> | null = null;
+  let pending: Promise<string | null> | null = null;
+  let custodyGeneration = 0;
+
+  async function exchange(generation: number): Promise<string | null> {
+    const first = await requestToken(fetcher, now);
+    const result = first.kind === "refresh_required"
+      ? await (async () => {
+          await refreshSuiteSession();
+          return await requestToken(fetcher, now);
+        })()
+      : first;
+    if (result.kind === "refresh_required") {
+      throw new Error("The suite session still requires refresh.");
+    }
+    if (result.kind === "signed_out") {
+      if (custodyGeneration === generation) cached = null;
+      return null;
+    }
+    if (custodyGeneration !== generation) return null;
+    cached = { expiresAtMs: result.expiresAtMs, token: result.token };
+    return result.token;
+  }
+
+  return Object.freeze({
+    clear() {
+      custodyGeneration += 1;
+      cached = null;
+    },
+    async fetchAccessToken() {
+      const nowMs = now();
+      if (
+        cached !== null
+        && cached.expiresAtMs - nowMs
+          >= SUITE_CONVEX_BROWSER_PARENT_REFRESH_WINDOW_MS
+      ) {
+        return cached.token;
+      }
+      if (pending !== null) return await pending;
+      const request = exchange(custodyGeneration);
+      pending = request;
+      try {
+        return await request;
+      } finally {
+        if (pending === request) pending = null;
+      }
+    },
+  });
+}