@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/layers/dms-auth/server/actions.ts

@@ -0,0 +1,251 @@
+import type { DmsServerEvent } from "#dms/server";
+import {
+  isPersistent,
+  persistAccountSession,
+  readAccount,
+  removeAccount,
+  storeAccount,
+  type StoredAccount,
+} from "./accounts";
+import { isRefusal, type SessionTokens, sessionFrom } from "./session";
+
+// Carries the "keep me signed in" choice of a login across its 2FA step, whose
+// request names only the challenge. Lives as long as the challenge token.
+const PENDING_LOGIN = "dms_pending_login";
+const PENDING_LOGIN_PATH = "/auth/verify-2fa";
+const PENDING_LOGIN_LIFETIME_S = 300;
+
+// Absolute backend API paths only: no scheme, no authority, no query string,
+// and no segment that could climb out of `/api/`.
+const BACKEND_API_PATH =
+  /^\/api\/[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9][A-Za-z0-9._~-]*)*$/;
+
+type Input = Record<string, unknown>;
+
+interface EstablishResult extends SessionTokens {
+  requires_2fa?: boolean;
+  requires_tenant_assignment?: boolean;
+  two_factor_token?: string;
+}
+
+interface PendingLogin {
+  token: string;
+  persistent: boolean;
+}
+
+/**
+ * Calls a backend endpoint that opens a session and, unless it asks for a
+ * second step, writes the session and stores the account.
+ */
+async function establishWith(
+  event: DmsServerEvent,
+  endpoint: string,
+  payload: unknown,
+  persistent = true,
+) {
+  const result = await event.backend<EstablishResult>(endpoint, {
+    method: "POST",
+    body: payload,
+  });
+  if (result.requires_2fa && typeof result.two_factor_token === "string")
+    event.cookies.writeSealed(
+      PENDING_LOGIN,
+      { token: result.two_factor_token, persistent },
+      { maxAge: PENDING_LOGIN_LIFETIME_S, path: PENDING_LOGIN_PATH },
+    );
+  if (result.requires_2fa || result.requires_tenant_assignment) return result;
+  if (event.cookies.readSealed(PENDING_LOGIN))
+    event.cookies.clear(PENDING_LOGIN, { path: PENDING_LOGIN_PATH });
+  const account = persistAccountSession(event, sessionFrom(result, persistent));
+  return { user: result.user, account };
+}
+
+/**
+ * `POST /auth/login`: signs in with a password. Only a login that asked to be
+ * kept signed in outlives the browser; any other ends when the browser closes.
+ */
+export async function login(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  return establishWith(
+    event,
+    "/api/auth/login",
+    input,
+    input.keep_login === true,
+  );
+}
+
+/** `POST /auth/register`: the signup page itself is `/auth/signup`. */
+export async function signup(event: DmsServerEvent) {
+  return establishWith(event, "/api/auth/signup", await event.readJson());
+}
+
+/**
+ * `POST /auth/verify-2fa`: finishes a login on its 2FA step, with the lifetime
+ * the login chose. A challenge that no login of this browser left a choice
+ * for, such as the one an OAuth sign-in hands over, keeps the default.
+ */
+export async function verifyTwoFactor(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  const pending = event.cookies.readSealed<PendingLogin>(PENDING_LOGIN);
+  const persistent =
+    typeof input.token === "string" && pending?.token === input.token
+      ? isPersistent(pending)
+      : true;
+  return establishWith(event, "/api/auth/verify-2fa", input, persistent);
+}
+
+/** `POST /auth/request-2fa-email`: relayed to the backend as is. */
+export async function requestTwoFactorEmail(event: DmsServerEvent) {
+  return event.backend("/api/auth/request-2fa-email", {
+    method: "POST",
+    body: await event.readJson(),
+  });
+}
+
+/**
+ * Whether a caller-named endpoint is one of the declared ones. The grammar is
+ * checked on the caller's value too, so a declaration that was never meant to
+ * be a prefix cannot be widened by a traversal or a query string smuggled
+ * into the request.
+ */
+export function isAllowedEstablishEndpoint(
+  endpoint: unknown,
+  allowed: readonly string[],
+): endpoint is string {
+  return (
+    typeof endpoint === "string" &&
+    BACKEND_API_PATH.test(endpoint) &&
+    allowed.includes(endpoint)
+  );
+}
+
+/**
+ * `POST /auth/establish`: opens a session from a backend endpoint that mints a
+ * token pair, the generic half of `/auth/login`. A module whose own flow ends
+ * in an authenticated user (a registration completing, an invitation being
+ * redeemed) declares the backend route that finishes it
+ * (`authEstablishEndpoints`, or `DMS_AUTH_ESTABLISH_ENDPOINTS`); the browser
+ * names it and a payload, and never carries a token.
+ */
+export async function establish(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  if (
+    !isAllowedEstablishEndpoint(
+      input.endpoint,
+      event.app.authEstablishEndpoints,
+    )
+  )
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  return establishWith(event, input.endpoint, input.payload ?? {});
+}
+
+/** `POST /auth/remove-account`: forgets a stored account. */
+export async function removeStoredAccount(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  removeAccount(event, input.accountId);
+  return { success: true };
+}
+
+/** `POST /auth/switch-tenant`: the same account, in another tenant. */
+export async function switchTenant(event: DmsServerEvent) {
+  const session = event.session.read();
+  const input = await event.readJson<Input>();
+  if (!session)
+    return Response.json({ message: "Not authenticated" }, { status: 401 });
+  if (!input.tenantId)
+    return Response.json({ message: "tenantId required" }, { status: 400 });
+  const tokens = await event.backend<SessionTokens>("/api/auth/switch-tenant", {
+    method: "POST",
+    token: session.accessToken,
+    body: { refreshToken: session.refreshToken, tenantId: input.tenantId },
+  });
+  const user = await event.backend<SessionTokens["user"]>("/api/auth/me", {
+    token: tokens.access_token,
+  });
+  const switched = sessionFrom({ ...tokens, user }, isPersistent(session));
+  persistAccountSession(event, switched, session.accountId);
+  return { success: true, user };
+}
+
+/** `POST /auth/switch-account`: signs in as another stored account. */
+export async function switchAccount(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  const account = readAccount(event, input.accountId);
+  if (!account)
+    return Response.json({ message: "Account expired" }, { status: 401 });
+  try {
+    const tokens = await event.backend<SessionTokens>("/api/auth/refresh", {
+      method: "POST",
+      body: { token: account.refreshToken },
+    });
+    const user = await event.backend<SessionTokens["user"]>("/api/auth/me", {
+      token: tokens.access_token,
+    });
+    const session = sessionFrom({ ...tokens, user }, isPersistent(account));
+    const descriptor = persistAccountSession(
+      event,
+      session,
+      input.accountId as string,
+    );
+    return { success: true, user, account: descriptor };
+  } catch (error) {
+    if (isRefusal(error)) removeAccount(event, input.accountId);
+    throw error;
+  }
+}
+
+/**
+ * Keep the tokens a validation refreshed, without changing which account is
+ * signed in. Another account only has its own cookie updated. The current one
+ * also has the session updated, since a refresh may have rotated the token the
+ * session holds; it keeps its user as the backend gave it.
+ */
+function storeValidatedAccount(
+  event: DmsServerEvent,
+  account: StoredAccount,
+  accountId: string,
+  tokens: SessionTokens,
+) {
+  const current = event.session.read();
+  if (current?.accountId === accountId) {
+    persistAccountSession(
+      event,
+      sessionFrom({ ...tokens, user: current.user }, isPersistent(current)),
+      accountId,
+    );
+    return;
+  }
+  const user = {
+    _id: account.userId,
+    email: account.email,
+    name: account.name,
+  };
+  storeAccount(
+    event,
+    sessionFrom({ ...tokens, user }, isPersistent(account)),
+    accountId,
+  );
+}
+
+/**
+ * `POST /auth/validate-account`: whether a stored account can still sign in,
+ * keeping the tokens the check refreshed. `null` when the backend could not
+ * tell.
+ */
+export async function validateAccount(event: DmsServerEvent) {
+  const input = await event.readJson<Input>();
+  const account = readAccount(event, input.accountId);
+  if (!account) return { valid: false };
+  try {
+    const tokens = await event.backend<SessionTokens>("/api/auth/refresh", {
+      method: "POST",
+      body: { token: account.refreshToken },
+    });
+    storeValidatedAccount(event, account, input.accountId as string, tokens);
+    return { valid: true };
+  } catch (error) {
+    const rejected = isRefusal(error);
+    if (rejected) removeAccount(event, input.accountId);
+    return { valid: rejected ? false : null };
+  }
+}

package/frontend-vue/layers/dms-auth/server/oauth.ts

@@ -0,0 +1,260 @@
+import { timingSafeEqual } from "node:crypto";
+import type { DmsServerEvent } from "#dms/server";
+import { privateSecret } from "../../../server/private-options";
+import { persistAccountSession } from "./accounts";
+import { type SessionTokens, sessionFrom } from "./session";
+
+// The provider sign-in, on the frontend's origin: the backend builds the
+// provider's URL and its callback (`relay.ts`, `config.ts`) and checks the
+// relay header this server sends, from the DMS module's private options.
+
+const FLOW = "dms_oauth_flow";
+const HANDOFF = "dms_oauth_handoff";
+const FLOW_PATH = "/auth/oauth";
+const COMPLETE = "/auth/oauth/complete";
+const SIGN_IN = "/auth";
+const OAUTH_ERROR = "error.oauth.";
+const FAILED = "error.oauth.failed";
+const FLOW_LIFETIME_MS = 10 * 60 * 1000;
+const HANDOFF_LIFETIME_S = 300;
+const RATE_WINDOW_MS = 60 * 1000;
+const RATE_LIMIT = 10;
+const MAX_RATE_LIMIT_CLIENTS = 10_000;
+const MAX_CALLBACK_PARAMETER_LENGTH = 2048;
+const PROVIDER = /^[a-z0-9-]{1,32}$/;
+
+interface RateWindow {
+  count: number;
+  startedAt: number;
+}
+
+interface OAuthFlow {
+  state: string;
+  expiresAt: number;
+  redirect: string;
+  language: string;
+  invite: string;
+}
+
+interface OAuthResult extends SessionTokens {
+  requires_2fa?: boolean;
+  requires_tenant_assignment?: boolean;
+  two_factor_token?: string;
+  tenant_assignment_token?: string;
+  methods?: unknown;
+}
+
+// Process-local, like the session refresh: one frontend process per sticky
+// client. A development reload of this file starts it over.
+const attempts = new Map<string, RateWindow>();
+
+function sweepAttempts(now: number) {
+  for (const [key, window] of attempts)
+    if (now - window.startedAt >= RATE_WINDOW_MS) attempts.delete(key);
+  while (attempts.size >= MAX_RATE_LIMIT_CLIENTS)
+    attempts.delete(attempts.keys().next().value as string);
+}
+
+/** Counts an attempt for `key`; false once over the limit of the window. */
+export function hitOAuthRateLimitKey(key: string, now = Date.now()): boolean {
+  sweepAttempts(now);
+  const window = attempts.get(key);
+  if (!window || now - window.startedAt >= RATE_WINDOW_MS) {
+    attempts.set(key, { count: 1, startedAt: now });
+    return true;
+  }
+  window.count += 1;
+  return window.count <= RATE_LIMIT;
+}
+
+function rateLimited(event: DmsServerEvent, scope: string): boolean {
+  return !hitOAuthRateLimitKey(`${scope}:${event.clientIp()}`);
+}
+
+export function isValidOAuthProvider(provider: unknown): provider is string {
+  return typeof provider === "string" && PROVIDER.test(provider);
+}
+
+function safePath(value: string | null): string {
+  if (
+    typeof value !== "string" ||
+    !value.startsWith("/") ||
+    value.startsWith("//") ||
+    value.includes("\\")
+  )
+    return "";
+  try {
+    const decoded = decodeURIComponent(value);
+    return decoded.startsWith("//") || decoded.includes("\\") ? "" : value;
+  } catch {
+    return "";
+  }
+}
+
+function redirect(location: string): Response {
+  return new Response(null, { status: 302, headers: { location } });
+}
+
+function errorRedirect(key: string): Response {
+  return redirect(`${SIGN_IN}?oauth_error=${encodeURIComponent(key)}`);
+}
+
+// The backend's own OAuth key says why a provider sign-in failed; any other
+// failure keeps the generic one.
+function failureRedirect(error: unknown): Response {
+  const message = error instanceof Error ? error.message : "";
+  const status = (error as { status?: unknown }).status;
+  return errorRedirect(
+    typeof status === "number" && message.startsWith(OAUTH_ERROR)
+      ? message
+      : FAILED,
+  );
+}
+
+function relayHeaders(event: DmsServerEvent): Record<string, string> {
+  const secret = privateSecret(
+    event,
+    "oauth",
+    "relaySecret",
+    "DMS_OAUTH_RELAY_SECRET",
+  );
+  return { "x-dms-oauth-relay": secret ?? "" };
+}
+
+/** `GET /auth/oauth/:provider/start`: on to the provider's sign-in page. */
+export async function oauthStart(event: DmsServerEvent): Promise<Response> {
+  const { provider } = event.params;
+  if (
+    !isValidOAuthProvider(provider) ||
+    event.request.headers.get("sec-fetch-site") === "cross-site" ||
+    rateLimited(event, "start")
+  )
+    return errorRedirect(FAILED);
+  try {
+    const result = await event.backend<{
+      state: string;
+      authorizeUrl: string;
+    }>(`/api/auth/oauth/${provider}/authorize-url`, {
+      headers: relayHeaders(event),
+    });
+    const query = event.url.searchParams;
+    event.cookies.writeSealed(
+      FLOW,
+      {
+        state: result.state,
+        expiresAt: Date.now() + FLOW_LIFETIME_MS,
+        redirect: safePath(query.get("redirect")),
+        language: query.get("language") ?? "",
+        invite: query.get("invite") ?? "",
+      } satisfies OAuthFlow,
+      { maxAge: FLOW_LIFETIME_MS / 1000, path: FLOW_PATH },
+    );
+    return redirect(result.authorizeUrl);
+  } catch (error) {
+    return failureRedirect(error);
+  }
+}
+
+function sameState(left: unknown, right: unknown): boolean {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function validCallback(flow: OAuthFlow | undefined, query: URLSearchParams) {
+  const code = query.get("code");
+  const state = query.get("state");
+  return Boolean(
+    flow &&
+      flow.expiresAt >= Date.now() &&
+      typeof code === "string" &&
+      code.length <= MAX_CALLBACK_PARAMETER_LENGTH &&
+      typeof state === "string" &&
+      state.length <= MAX_CALLBACK_PARAMETER_LENGTH &&
+      sameState(state, flow.state),
+  );
+}
+
+function storeOAuthResult(
+  event: DmsServerEvent,
+  provider: string,
+  result: OAuthResult,
+) {
+  const handoff = { maxAge: HANDOFF_LIFETIME_S, path: FLOW_PATH };
+  if (result.requires_2fa)
+    event.cookies.writeSealed(
+      HANDOFF,
+      { kind: "2fa", token: result.two_factor_token, methods: result.methods },
+      handoff,
+    );
+  else if (result.requires_tenant_assignment)
+    event.cookies.writeSealed(
+      HANDOFF,
+      {
+        kind: "no-workspace",
+        token: result.tenant_assignment_token,
+        provider,
+      },
+      handoff,
+    );
+  else persistAccountSession(event, sessionFrom(result));
+}
+
+async function completeOAuth(
+  event: DmsServerEvent,
+  provider: string,
+  flow: OAuthFlow,
+): Promise<Response> {
+  const query = event.url.searchParams;
+  try {
+    const result = await event.backend<OAuthResult>(
+      `/api/auth/oauth/${provider}/callback`,
+      {
+        method: "POST",
+        headers: relayHeaders(event),
+        body: {
+          code: query.get("code"),
+          state: query.get("state"),
+          state_cookie: flow.state,
+          language: flow.language || undefined,
+          invite: flow.invite || undefined,
+        },
+      },
+    );
+    storeOAuthResult(event, provider, result);
+    return redirect(
+      flow.redirect &&
+        !result.requires_2fa &&
+        !result.requires_tenant_assignment
+        ? `${COMPLETE}?redirect=${encodeURIComponent(flow.redirect)}`
+        : COMPLETE,
+    );
+  } catch (error) {
+    return failureRedirect(error);
+  }
+}
+
+/** `GET /auth/oauth/:provider/callback`: back from the provider. */
+export async function oauthCallback(event: DmsServerEvent): Promise<Response> {
+  const { provider } = event.params;
+  if (!isValidOAuthProvider(provider) || rateLimited(event, "callback"))
+    return errorRedirect(FAILED);
+  const flow = event.cookies.readSealed<OAuthFlow>(FLOW);
+  event.cookies.clear(FLOW, { path: FLOW_PATH });
+  const query = event.url.searchParams;
+  if (query.has("error")) return errorRedirect("error.oauth.cancelled");
+  if (!flow || !validCallback(flow, query))
+    return errorRedirect("error.oauth.invalid_state");
+  return completeOAuth(event, provider, flow);
+}
+
+/**
+ * `POST /auth/oauth/handoff`: what the provider sign-in left for the page to
+ * finish (a 2FA step, a workspace to pick), once.
+ */
+export function oauthHandoff(event: DmsServerEvent) {
+  const handoff = event.cookies.readSealed(HANDOFF) ?? { kind: "none" };
+  event.cookies.clear(HANDOFF, { path: FLOW_PATH });
+  return handoff;
+}

package/frontend-vue/layers/dms-auth/server/session.ts

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import type { DmsPublicSession, DmsServerEvent, DmsSession } from "#dms/server";
+import { isPersistent, persistAccountSession, removeAccount } from "./accounts";
+
+const REFRESH_TTL_MS = 15_000;
+const REFUSED = [400, 401, 403];
+
+/** A backend answer that opens a session: a token pair and the user. */
+export interface SessionTokens {
+  access_token: string;
+  refresh_token?: string;
+  user?: DmsSession["user"];
+}
+
+interface RefreshFlight {
+  promise: Promise<SessionTokens>;
+  expiresAt?: number;
+}
+
+const refreshes = new Map<string, RefreshFlight>();
+
+export function isRefusal(error: unknown): boolean {
+  const status = (error as { status?: unknown } | undefined)?.status;
+  return typeof status === "number" && REFUSED.includes(status);
+}
+
+/**
+ * The session a token pair opens.
+ *
+ * @param result Backend answer carrying the tokens and the user
+ * @param persistent Whether the session outlives the browser
+ */
+export function sessionFrom(
+  result: SessionTokens,
+  persistent = true,
+): DmsSession {
+  const payload = JSON.parse(
+    Buffer.from(
+      result.access_token.split(".")[1] ?? "",
+      "base64url",
+    ).toString() || "{}",
+  ) as { tenantId?: string };
+  return {
+    user: result.user,
+    accessToken: result.access_token,
+    refreshToken: result.refresh_token,
+    activeTenantId: payload.tenantId ?? "default",
+    persistent,
+  };
+}
+
+/** What a signed-in session shows the browser; the server adds `updatedAt`. */
+export function publicSession(session: DmsSession): DmsPublicSession {
+  return {
+    user: session.user,
+    session: {
+      accountId: session.accountId,
+      activeTenantId: session.activeTenantId,
+    },
+  };
+}
+
+/**
+ * One backend refresh per refresh token at a time: the requests a page fires
+ * together after its access token expired share it, rather than spending the
+ * rotating refresh token several times over. Kept a while after it settles
+ * for the requests that were already on their way.
+ */
+function singleFlight(
+  token: string,
+  operation: () => Promise<SessionTokens>,
+): Promise<SessionTokens> {
+  const now = Date.now();
+  for (const [key, entry] of refreshes)
+    if (entry.expiresAt && entry.expiresAt <= now) refreshes.delete(key);
+  const key = createHash("sha256").update(token).digest("base64url");
+  const current = refreshes.get(key);
+  if (current) return current.promise;
+  const entry: RefreshFlight = { promise: Promise.resolve().then(operation) };
+  refreshes.set(key, entry);
+  const retain = () => {
+    entry.expiresAt = Date.now() + REFRESH_TTL_MS;
+    setTimeout(() => {
+      if (refreshes.get(key) === entry) refreshes.delete(key);
+    }, REFRESH_TTL_MS).unref();
+  };
+  entry.promise.then(retain, retain);
+  return entry.promise;
+}
+
+/**
+ * Renews `session` with its refresh token, writes it and returns it; the rest
+ * of the request runs with it. A refused refresh signs the browser out.
+ * The frontend server calls it when the backend refuses a signed-in page
+ * visit, and `POST /api/_auth/session` when the browser asks.
+ */
+export async function renewSession(
+  event: DmsServerEvent,
+  session: DmsSession | undefined = event.session.read(),
+): Promise<DmsSession | undefined> {
+  const refreshToken = session?.refreshToken;
+  if (!session || !refreshToken) return undefined;
+  try {
+    const tokens = await singleFlight(refreshToken, () =>
+      event.backend<SessionTokens>("/api/auth/refresh", {
+        method: "POST",
+        token: session.accessToken,
+        body: { token: refreshToken },
+      }),
+    );
+    const user = await event.backend<DmsSession["user"]>("/api/auth/me", {
+      token: tokens.access_token,
+    });
+    const refreshed = sessionFrom({ ...tokens, user }, isPersistent(session));
+    persistAccountSession(event, refreshed, session.accountId);
+    event.session.useForRequest(refreshed);
+    return refreshed;
+  } catch (error) {
+    if (isRefusal(error)) event.session.clear();
+    event.session.useForRequest(undefined);
+    return undefined;
+  }
+}
+
+/** `GET /api/_auth/session`: the session as the browser sees it. */
+export function readSessionRoute(event: DmsServerEvent) {
+  return event.session.view();
+}
+
+/** `POST /api/_auth/session`: renews the session, then shows it. */
+export async function refreshSessionRoute(event: DmsServerEvent) {
+  await renewSession(event);
+  return event.session.view();
+}
+
+/** `DELETE /api/_auth/session`: signs out, on the backend too. */
+export async function logoutRoute(event: DmsServerEvent) {
+  const session = event.session.read();
+  if (session?.refreshToken && session.accessToken)
+    await event
+      .backend("/api/auth/logout", {
+        method: "POST",
+        token: session.accessToken,
+        body: { token: session.refreshToken },
+      })
+      .catch(() => {});
+  event.session.clear();
+  if (session?.accountId) removeAccount(event, session.accountId);
+  return {};
+}
+
+/** Any other method on `/api/_auth/session`. */
+export function sessionMethodNotAllowed() {
+  return Response.json(
+    { error: "Method Not Allowed" },
+    { status: 405, headers: { allow: "GET, POST, DELETE" } },
+  );
+}