@manta-eu/auth 0.1.8 → 0.1.10

package/src/web-routes.ts

@@ -0,0 +1,321 @@
+import { EncryptJWT, jwtDecrypt, type JWTPayload } from "jose";
+import type { FetchLike } from "./http.js";
+import type { OidcClient } from "./oidc.js";
+import { accessTokenExpiresAt } from "./token.js";
+import {
+  endWebLogin,
+  finishWebLogin,
+  refreshWebLogin,
+  startWebLogin,
+  webLogoutUrl,
+  type WebTokens,
+} from "./web-login.js";
+
+export type WebLoginRoutesOptions = {
+  /** A confidential client: a custom app's client ID and secret, plus `baseUrl` and `realm` off hiremanta.com. */
+  client: OidcClient & { clientSecret: string };
+  /** Where the app runs, e.g. `https://app.example.com`; `paths.callback` under it must be a registered redirect URL. */
+  appUrl: string;
+  /** At least 32 characters, kept on the server. Rotating it signs everyone out. */
+  sessionSecret: string;
+  paths?: { login?: string; callback?: string; logout?: string };
+  /** Where people land after signing in (unless `/login?returnTo=` names a page) and after signing out. */
+  afterLogin?: string;
+  afterLogout?: string;
+  offlineAccess?: boolean;
+  idpHint?: string;
+  /** Off signs people out of this app only; on (the default) ends their Manta session too. */
+  signOutOfManta?: boolean;
+  cookieName?: string;
+  fetchImpl?: FetchLike;
+};
+
+export type WebSession = {
+  /** Absent when no one is signed in, or the session could not be renewed. */
+  accessToken: string | undefined;
+  idToken?: string;
+  /** Set-Cookie values to add to the response: a renewed session, or one cleared after a refused renewal. */
+  setCookies: string[];
+};
+
+export type WebLoginRoutes = {
+  /** Answers the login, callback and logout paths; `undefined` for any other request. */
+  handle(request: Request): Promise<Response | undefined>;
+  /** The signed-in person's access token, renewed when it is about to expire. */
+  session(request: Request): Promise<WebSession>;
+};
+
+type StoredSession = { accessToken: string; refreshToken?: string; idToken?: string };
+
+type PendingLogin = { state: string; verifier: string; returnTo: string };
+
+type SharedRefresh = { renewed: Promise<WebTokens | undefined>; settledAt?: number; nextRefreshToken?: string };
+
+type SealingKey = Awaited<ReturnType<typeof crypto.subtle.deriveKey>>;
+
+const loginTtlMs = 10 * 60 * 1000;
+const offlineCookieMaxAgeSeconds = 30 * 24 * 60 * 60;
+const chunkSize = 3800;
+const maxChunks = 10;
+const refreshReuseMs = 10_000;
+
+// One key per purpose, so a login cookie can never be replayed as a session cookie or the other way round.
+async function purposeKey(secret: string, purpose: string): Promise<SealingKey> {
+  const material = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new TextEncoder().encode("manta-web-login"),
+      info: new TextEncoder().encode(purpose),
+    },
+    material,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+async function seal(key: SealingKey, value: StoredSession | PendingLogin, ttlMs?: number): Promise<string> {
+  const jwt = new EncryptJWT({ ...value }).setProtectedHeader({ alg: "dir", enc: "A256GCM" });
+  if (ttlMs !== undefined) jwt.setExpirationTime(new Date(Date.now() + ttlMs));
+  return jwt.encrypt(key);
+}
+
+async function unseal(key: SealingKey, value: string | undefined): Promise<JWTPayload | undefined> {
+  if (!value) return undefined;
+  try {
+    return (await jwtDecrypt(value, key)).payload;
+  } catch {
+    return undefined;
+  }
+}
+
+function cookiesOf(request: Request): Map<string, string> {
+  const cookies = new Map<string, string>();
+  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
+    const separator = part.indexOf("=");
+    if (separator > 0) cookies.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+  }
+  return cookies;
+}
+
+// Only a path on the app itself, so `/login?returnTo=` can never send people to another site.
+// A browser drops tabs and newlines from a Location, so `/\t/evil.example` would land on `//evil.example`.
+function safeReturnTo(raw: string | null, fallback: string, appUrl: URL): string {
+  if (!raw?.startsWith("/") || /[\p{Cc}\\]/u.test(raw)) return fallback;
+  const resolved = new URL(raw, appUrl);
+  // Resolving drops dot segments, so `/.//evil.example` comes out as the protocol-relative `//evil.example`.
+  if (resolved.origin !== appUrl.origin || resolved.pathname.startsWith("//")) return fallback;
+  return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+
+function isStoredSession(value: unknown): value is StoredSession {
+  return typeof value === "object" && value !== null && typeof (value as StoredSession).accessToken === "string";
+}
+
+function isPendingLogin(value: unknown): value is PendingLogin {
+  if (typeof value !== "object" || value === null) return false;
+  const login = value as PendingLogin;
+  return typeof login.state === "string" && typeof login.verifier === "string" && typeof login.returnTo === "string";
+}
+
+function redirect(location: string, setCookies: string[] = []): Response {
+  const headers = new Headers({ location, "cache-control": "no-store" });
+  for (const cookie of setCookies) headers.append("set-cookie", cookie);
+  return new Response(null, { status: 302, headers });
+}
+
+/** Sign-in, callback and sign-out routes for a custom app's server, on standard Request and Response. */
+export function webLoginRoutes(options: WebLoginRoutesOptions): WebLoginRoutes {
+  if (options.sessionSecret.length < 32) throw new Error("sessionSecret must be at least 32 characters");
+
+  const appUrl = new URL(options.appUrl);
+  const secure = appUrl.protocol === "https:";
+  const paths = { login: "/login", callback: "/callback", logout: "/logout", ...options.paths };
+  const afterLogin = options.afterLogin ?? "/";
+  const afterLogout = options.afterLogout ?? "/";
+  const redirectUri = new URL(paths.callback, appUrl).toString();
+  const sessionName = options.cookieName ?? "manta_session";
+  const loginName = `${sessionName}_login`;
+  const keys = {
+    session: purposeKey(options.sessionSecret, "session"),
+    login: purposeKey(options.sessionSecret, "login"),
+  };
+  const { client, fetchImpl } = options;
+  // Keycloak takes a refresh token at most twice, so requests racing one expired session share one refresh,
+  // and so do requests that arrive with the old cookie shortly after it.
+  const refreshes = new Map<string, SharedRefresh>();
+
+  function refreshOnce(refreshToken: string): Promise<WebTokens | undefined> {
+    const now = Date.now();
+    for (const [token, { settledAt }] of refreshes) {
+      if (settledAt !== undefined && now - settledAt > refreshReuseMs) refreshes.delete(token);
+    }
+    const known = refreshes.get(refreshToken);
+    if (known) return known.renewed;
+    const entry: SharedRefresh = { renewed: refreshWebLogin(client, refreshToken, fetchImpl) };
+    refreshes.set(refreshToken, entry);
+    void entry.renewed.then(
+      (tokens) => {
+        entry.settledAt = Date.now();
+        entry.nextRefreshToken = tokens?.refreshToken;
+      },
+      () => refreshes.delete(refreshToken),
+    );
+    return entry.renewed;
+  }
+
+  // A signed-out session must not come back through a refresh shared with a request that still holds an older cookie.
+  function forgetRefreshes(endedRefreshToken: string) {
+    const ended = new Set([endedRefreshToken]);
+    for (const [token, { nextRefreshToken }] of [...refreshes].reverse()) {
+      if (ended.has(token) || (nextRefreshToken !== undefined && ended.has(nextRefreshToken))) {
+        ended.add(token);
+        refreshes.delete(token);
+      }
+    }
+  }
+
+  function cookie(name: string, value: string, extra: { path?: string; maxAge?: number } = {}): string {
+    const attributes = [`${name}=${value}`, `Path=${extra.path ?? "/"}`, "HttpOnly", "SameSite=Lax"];
+    if (secure) attributes.push("Secure");
+    if (extra.maxAge !== undefined) attributes.push(`Max-Age=${extra.maxAge}`);
+    return attributes.join("; ");
+  }
+
+  function clearedSession(cookies: Map<string, string>): string[] {
+    return [...cookies.keys()]
+      .filter((name) => name.startsWith(`${sessionName}.`))
+      .map((name) => cookie(name, "", { maxAge: 0 }));
+  }
+
+  async function sessionCookies(stored: StoredSession, cookies: Map<string, string>): Promise<string[]> {
+    const value = await seal(await keys.session, stored);
+    const chunks = Math.ceil(value.length / chunkSize);
+    if (chunks > maxChunks) throw new Error("The session is too large to keep in cookies");
+    const maxAge = options.offlineAccess === true ? offlineCookieMaxAgeSeconds : undefined;
+    const written = Array.from({ length: chunks }, (_, index) =>
+      cookie(`${sessionName}.${index}`, value.slice(index * chunkSize, (index + 1) * chunkSize), {
+        ...(maxAge === undefined ? {} : { maxAge }),
+      }),
+    );
+    const stale = [...cookies.keys()]
+      .filter((name) => name.startsWith(`${sessionName}.`) && Number(name.slice(sessionName.length + 1)) >= chunks)
+      .map((name) => cookie(name, "", { maxAge: 0 }));
+    return [...written, ...stale];
+  }
+
+  async function storedSession(cookies: Map<string, string>): Promise<StoredSession | undefined> {
+    let value = "";
+    for (let index = 0; cookies.has(`${sessionName}.${index}`); index += 1) {
+      value += cookies.get(`${sessionName}.${index}`);
+    }
+    const stored = await unseal(await keys.session, value);
+    return isStoredSession(stored) ? stored : undefined;
+  }
+
+  async function login(request: Request): Promise<Response> {
+    const returnTo = safeReturnTo(new URL(request.url).searchParams.get("returnTo"), afterLogin, appUrl);
+    const { url, state, verifier } = await startWebLogin(client, {
+      redirectUri,
+      ...(options.offlineAccess === true ? { offlineAccess: true } : {}),
+      ...(options.idpHint ? { idpHint: options.idpHint } : {}),
+    });
+    const sealed = await seal(await keys.login, { state, verifier, returnTo } satisfies PendingLogin, loginTtlMs);
+    return redirect(url, [cookie(loginName, sealed, { path: paths.callback, maxAge: loginTtlMs / 1000 })]);
+  }
+
+  async function callback(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const cookies = cookiesOf(request);
+    const clearLogin = cookie(loginName, "", { path: paths.callback, maxAge: 0 });
+    const pending = await unseal(await keys.login, cookies.get(loginName));
+    const failed = (reason: string) =>
+      new Response(`Sign-in failed: ${reason}`, { status: 400, headers: { "set-cookie": clearLogin } });
+
+    if (url.searchParams.has("error")) {
+      return failed(url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "refused");
+    }
+    if (!isPendingLogin(pending)) return failed("the sign-in expired, start again");
+    if (url.searchParams.get("state") !== pending.state) return failed("the sign-in does not match this browser");
+    const code = url.searchParams.get("code");
+    if (!code) return failed("no code");
+
+    const tokens = await finishWebLogin(
+      client,
+      { code, redirectUri, verifier: pending.verifier, callbackUrl: url.toString(), state: pending.state },
+      fetchImpl,
+    );
+    const stored: StoredSession = {
+      accessToken: tokens.accessToken,
+      ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
+      ...(tokens.idToken ? { idToken: tokens.idToken } : {}),
+    };
+    return redirect(pending.returnTo, [...(await sessionCookies(stored, cookies)), clearLogin]);
+  }
+
+  async function logout(request: Request): Promise<Response> {
+    const cookies = cookiesOf(request);
+    const stored = await storedSession(cookies);
+    if (stored?.refreshToken) {
+      forgetRefreshes(stored.refreshToken);
+      await endWebLogin(client, stored.refreshToken, fetchImpl);
+    }
+    // Keycloak matches this exactly against the app's redirect URLs and home URL, which has no trailing slash.
+    const landing = afterLogout === "/" ? options.appUrl.replace(/\/+$/, "") : new URL(afterLogout, appUrl).toString();
+    const target =
+      options.signOutOfManta === false
+        ? afterLogout
+        : webLogoutUrl(client, {
+            ...(stored?.idToken ? { idToken: stored.idToken } : {}),
+            postLogoutRedirectUri: landing,
+          });
+    return redirect(target, clearedSession(cookies));
+  }
+
+  return {
+    async handle(request) {
+      const { pathname } = new URL(request.url);
+      if (pathname === paths.login && request.method === "GET") return login(request);
+      if (pathname === paths.callback && request.method === "GET") return callback(request);
+      if (pathname === paths.logout && (request.method === "GET" || request.method === "POST")) {
+        // The session cookies are SameSite=Lax, so a link from another site would otherwise sign the person out.
+        const site = request.headers.get("sec-fetch-site");
+        if (site === "cross-site" || site === "same-site")
+          return new Response("Sign out from the app", { status: 403 });
+        return logout(request);
+      }
+      return undefined;
+    },
+
+    async session(request) {
+      const cookies = cookiesOf(request);
+      const stored = await storedSession(cookies);
+      if (!stored) return { accessToken: undefined, setCookies: [] };
+
+      const now = Date.now();
+      if (accessTokenExpiresAt(stored.accessToken, now) > now) {
+        return {
+          accessToken: stored.accessToken,
+          ...(stored.idToken ? { idToken: stored.idToken } : {}),
+          setCookies: [],
+        };
+      }
+
+      const renewed = stored.refreshToken ? await refreshOnce(stored.refreshToken) : undefined;
+      if (!renewed) return { accessToken: undefined, setCookies: clearedSession(cookies) };
+
+      const next: StoredSession = {
+        accessToken: renewed.accessToken,
+        ...(renewed.refreshToken ? { refreshToken: renewed.refreshToken } : {}),
+        ...((renewed.idToken ?? stored.idToken) ? { idToken: renewed.idToken ?? stored.idToken } : {}),
+      };
+      return {
+        accessToken: next.accessToken,
+        ...(next.idToken ? { idToken: next.idToken } : {}),
+        setCookies: await sessionCookies(next, cookies),
+      };
+    },
+  };
+}

package/src/web.ts

@@ -0,0 +1,25 @@
+export { defaultDeployment } from "./default-deployment.js";
+export type { PublicClient } from "./device-login.js";
+export { describeError, isTransientStatus, RefusedRequestError, type FetchLike } from "./http.js";
+export { discoveryUrl, issuerUrl, type OidcClient, type Realm } from "./oidc.js";
+export {
+  accessTokenExpiresAt,
+  cachedToken,
+  mintWithClientCredentials,
+  withRenewal,
+  type ClientCredentials,
+  type RenewableTokenSource,
+  type TokenSource,
+} from "./token.js";
+export {
+  endWebLogin,
+  finishWebLogin,
+  refreshWebLogin,
+  startWebLogin,
+  webLogoutUrl,
+  type StartWebLoginOptions,
+  type WebLoginStart,
+  type WebLogoutOptions,
+  type WebTokens,
+} from "./web-login.js";
+export { webLoginRoutes, type WebLoginRoutes, type WebLoginRoutesOptions, type WebSession } from "./web-routes.js";