@businessdash/sdk 0.9.60

package/src/auth-handler.ts

@@ -0,0 +1,352 @@
+/**
+ * SDK auth handler — the file a tenant developer mounts on their own site
+ * to handle the platform auth-provider callback. Cookie lives on the tenant's
+ * domain so the tenant's SSR can read it via standard cookie APIs.
+ *
+ * Usage (Next.js App Router):
+ *
+ *   // app/api/biab-auth/[...biab]/route.ts
+ *   import { createAuthHandler } from "@businessdash/sdk";
+ *
+ *   const handler = createAuthHandler({
+ *     baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+ *     apiKey: process.env.BIAB_API_KEY!,
+ *     callbackUrl: "https://my-site.com/api/biab-auth/callback",
+ *   });
+ *
+ *   export const GET = handler.GET;
+ *   export const POST = handler.POST;
+ *
+ * Then drop <SignIn />, <SignUp />, <SignOut /> into your pages — they call
+ * `/api/biab-auth/sign-in?intent=sign-in` etc., which 302s through the
+ * platform-hosted auth page and back to `callbackUrl`. The handler exchanges
+ * the code,
+ * sets the session cookie, and redirects the user to `returnTo`.
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+import { BiabDevClient, type BiabDevClientOptions } from "./client.js";
+import { BiabApiError } from "./errors.js";
+
+export const DEFAULT_AUTH_COOKIE_NAME = "biab_session";
+export const DEFAULT_AUTH_BASE_PATH = "/api/biab-auth";
+
+export type CreateAuthHandlerOptions = {
+	/** BIAB platform base URL — e.g. https://app.biab.com/api/package/v1 */
+	baseUrl: string;
+	/** Org-bound package API key (server-side secret). */
+	apiKey: string;
+	/**
+	 * Public, fully-qualified URL of THIS handler's `/callback` route on the
+	 * tenant's domain. Must be registered as a redirect URI with the platform.
+	 */
+	callbackUrl: string;
+	/** Where to send the user after successful sign-in if no `returnTo` was passed. */
+	defaultReturnTo?: string;
+	/** Where to send the user after sign-out. Defaults to "/". */
+	signOutReturnTo?: string;
+	/** Cookie name. Defaults to "biab_session". */
+	cookieName?: string;
+	/**
+	 * Cookie domain. Leave undefined to scope to current host. Set if you want
+	 * to share the session across subdomains (e.g. ".my-site.com").
+	 */
+	cookieDomain?: string;
+	/**
+	 * The base path this handler is mounted at — used to derive sub-routes.
+	 * Defaults to "/api/biab-auth". Must match the route file location.
+	 */
+	basePath?: string;
+	/** Optional fetch override (testing, edge runtimes). */
+	fetch?: BiabDevClientOptions["fetch"];
+	/**
+	 * Origin sent on every server-to-server request to the platform. Defaults
+	 * to the origin of `callbackUrl`. Override only when your dev/prod hosts
+	 * differ from the callback (rare).
+	 */
+	siteOrigin?: string;
+};
+
+type SimpleHandler = (request: Request) => Promise<Response>;
+
+export type AuthHandlerRoutes = {
+	GET: SimpleHandler;
+	POST: SimpleHandler;
+};
+
+function buildSetCookie(
+	name: string,
+	value: string,
+	opts: {
+		expiresAt?: Date | undefined;
+		domain?: string | undefined;
+		clear?: boolean | undefined;
+	},
+): string {
+	const parts = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax"];
+	parts.push("Secure");
+	if (opts.domain) parts.push(`Domain=${opts.domain}`);
+	if (opts.clear) {
+		parts.push("Max-Age=0");
+	} else if (opts.expiresAt) {
+		parts.push(`Expires=${opts.expiresAt.toUTCString()}`);
+	}
+	return parts.join("; ");
+}
+
+function readCookie(request: Request, name: string): string | null {
+	const header = request.headers.get("cookie");
+	if (!header) return null;
+	for (const part of header.split(";")) {
+		const [k, ...rest] = part.trim().split("=");
+		if (k === name) return rest.join("=");
+	}
+	return null;
+}
+
+/**
+ * `auth/start` expects `returnTo` as an absolute URL. Plain paths like `/` come
+ * from `defaultReturnTo` and from `<SignIn returnTo="/dashboard" />`.
+ */
+function absolutizeReturnTo(returnTo: string, requestUrl: string): string {
+	try {
+		return new URL(returnTo, requestUrl).href;
+	} catch {
+		return new URL("/", requestUrl).href;
+	}
+}
+
+function decodeReturnTo(state: string | null): string | null {
+	if (!state) return null;
+	try {
+		const decoded = Buffer.from(state, "base64url").toString("utf8");
+		const parsed = JSON.parse(decoded) as { returnTo?: unknown };
+		if (typeof parsed.returnTo === "string") return parsed.returnTo;
+	} catch {
+		/* ignore */
+	}
+	return null;
+}
+
+/**
+ * Returned as plain text so failed redirects show a readable page instead of
+ * Next.js's empty 500 from an uncaught `BiabApiError`.
+ */
+function authStartFailureResponse(error: unknown): Response {
+	let detail = "";
+	if (error instanceof BiabApiError) {
+		const fromBody =
+			error.body &&
+			typeof error.body === "object" &&
+			"message" in error.body &&
+			typeof (error.body as { message: unknown }).message === "string"
+				? (error.body as { message: string }).message
+				: error.message;
+		detail = fromBody ? `${fromBody}\n\n` : "";
+		const needsTenantAuthHint =
+			error.status === 403 &&
+			(typeof fromBody === "string"
+				? /tenant_auth|missing_scope/i.test(fromBody)
+				: false);
+		if (needsTenantAuthHint) {
+			detail +=
+				"Signing in requires API scope tenant_auth:public (it is on by default in Site Builder → Developer).\n";
+			detail +=
+				"If scope is included but this still fails, deploy the latest BIAB app (pinned-site keys were broken on tenant auth routes) or use an org-wide key (no “Pin to current site”).\n";
+			detail +=
+				"Platform operators issuing keys separately: include tenant_auth under Scopes. Re-issue the key, set BIAB_API_KEY, redeploy.";
+		}
+		const status =
+			error.status >= 400 && error.status <= 599 ? error.status : 502;
+		return new Response(`${detail || "Tenant auth request failed."}`.trim(), {
+			status,
+			headers: { "Content-Type": "text/plain; charset=utf-8" },
+		});
+	}
+	const fallback =
+		error instanceof Error
+			? error.message
+			: "Unexpected error during tenant auth.";
+	return new Response(`Tenant auth request failed.\n\n${fallback}`.trim(), {
+		status: 502,
+		headers: { "Content-Type": "text/plain; charset=utf-8" },
+	});
+}
+
+export function createAuthHandler(
+	options: CreateAuthHandlerOptions,
+): AuthHandlerRoutes {
+	const cookieName = options.cookieName ?? DEFAULT_AUTH_COOKIE_NAME;
+	const basePath = (options.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(
+		/\/$/,
+		"",
+	);
+	const defaultReturnTo = options.defaultReturnTo ?? "/";
+	const signOutReturnTo = options.signOutReturnTo ?? "/";
+	const derivedOrigin =
+		options.siteOrigin ??
+		(() => {
+			try {
+				return new URL(options.callbackUrl).origin;
+			} catch {
+				return undefined;
+			}
+		})();
+	const client = new BiabDevClient({
+		baseUrl: options.baseUrl,
+		apiKey: options.apiKey,
+		...(options.fetch ? { fetch: options.fetch } : {}),
+		...(derivedOrigin ? { siteOrigin: derivedOrigin } : {}),
+	});
+
+	async function handle(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+		const subroute = url.pathname.startsWith(basePath)
+			? url.pathname.slice(basePath.length).replace(/^\//, "")
+			: url.pathname;
+
+		// /sign-in?returnTo=... and /sign-up?returnTo=...
+		if (subroute === "sign-in" || subroute === "sign-up") {
+			const rawReturnTo = url.searchParams.get("returnTo") ?? defaultReturnTo;
+			try {
+				const start = await client.auth.start({
+					intent: subroute === "sign-up" ? "sign-up" : "sign-in",
+					returnTo: absolutizeReturnTo(rawReturnTo, request.url),
+					redirectUri: options.callbackUrl,
+					loginHint: url.searchParams.get("loginHint") ?? undefined,
+				});
+				return Response.redirect(start.url, 302);
+			} catch (err) {
+				return authStartFailureResponse(err);
+			}
+		}
+
+		// /callback?code=...&state=...
+		if (subroute === "callback") {
+			const code = url.searchParams.get("code");
+			if (!code) {
+				return new Response("Missing code", { status: 400 });
+			}
+			const oauthState = url.searchParams.get("state");
+			if (!oauthState?.trim()) {
+				return new Response("Missing OAuth state", { status: 400 });
+			}
+			try {
+				const session = await client.auth.exchange({
+					code,
+					state: oauthState,
+					redirectUri: options.callbackUrl,
+				});
+				const returnTo =
+					decodeReturnTo(url.searchParams.get("state")) ?? defaultReturnTo;
+				return new Response(null, {
+					status: 302,
+					headers: {
+						Location: returnTo,
+						"Set-Cookie": buildSetCookie(cookieName, session.sessionToken, {
+							expiresAt: new Date(
+								Temporal.Instant.from(session.expiresAt).epochMilliseconds,
+							),
+							domain: options.cookieDomain,
+						}),
+					},
+				});
+			} catch (err) {
+				const message = err instanceof Error ? err.message : "exchange failed";
+				return new Response(`Sign-in failed: ${message}`, { status: 400 });
+			}
+		}
+
+		// /sign-out (GET → redirect, POST → JSON response for programmatic calls)
+		if (subroute === "sign-out") {
+			await client.auth.signOut().catch(() => undefined);
+			const clearCookieHeader = buildSetCookie(cookieName, "", {
+				clear: true,
+				domain: options.cookieDomain,
+			});
+			if (request.method === "POST") {
+				return new Response(JSON.stringify({ ok: true }), {
+					status: 200,
+					headers: {
+						"Content-Type": "application/json",
+						"Set-Cookie": clearCookieHeader,
+					},
+				});
+			}
+			return new Response(null, {
+				status: 302,
+				headers: {
+					Location: signOutReturnTo,
+					"Set-Cookie": clearCookieHeader,
+				},
+			});
+		}
+
+		// /password-reset (POST { email } → 200 ok). Always succeeds from the
+		// caller's perspective; the BIAB endpoint only emails when the address
+		// belongs to a member of the org bound to this handler's API key.
+		if (subroute === "password-reset" && request.method === "POST") {
+			let payload: { email?: unknown; returnTo?: unknown };
+			try {
+				payload = (await request.json()) as typeof payload;
+			} catch {
+				return new Response("Bad JSON", { status: 400 });
+			}
+			const email =
+				typeof payload.email === "string" ? payload.email.trim() : "";
+			if (!email) {
+				return new Response("email is required", { status: 400 });
+			}
+			try {
+				const result = await client.auth.requestPasswordReset({
+					email,
+					...(typeof payload.returnTo === "string"
+						? { returnTo: payload.returnTo }
+						: {}),
+				});
+				return Response.json(result);
+			} catch (err) {
+				return authStartFailureResponse(err);
+			}
+		}
+
+		// /me — returns the current session (or null) as JSON, scoped to this cookie.
+		if (subroute === "me") {
+			const token = readCookie(request, cookieName);
+			if (!token) {
+				return Response.json(null);
+			}
+			const me = await client.auth
+				.me({ sessionToken: token })
+				.catch(() => null);
+			return Response.json(me);
+		}
+
+		return new Response("Not found", { status: 404 });
+	}
+
+	return { GET: handle, POST: handle };
+}
+
+/**
+ * Server-side helper for tenant SSR: read the current session from the cookie.
+ * Returns null when the user isn't signed in.
+ */
+export async function getTenantSession(input: {
+	cookieValue: string | null | undefined;
+	baseUrl: string;
+	apiKey: string;
+	/** Required when the API key has Allowed Host set; see {@link BiabDevClientOptions.siteOrigin}. */
+	siteOrigin?: string;
+	fetch?: BiabDevClientOptions["fetch"];
+}) {
+	if (!input.cookieValue) return null;
+	const client = new BiabDevClient({
+		baseUrl: input.baseUrl,
+		apiKey: input.apiKey,
+		...(input.fetch ? { fetch: input.fetch } : {}),
+		...(input.siteOrigin ? { siteOrigin: input.siteOrigin } : {}),
+	});
+	return client.auth.me({ sessionToken: input.cookieValue }).catch(() => null);
+}