@growth-labs/auth 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/auth",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -33,6 +33,11 @@
   },
   "files": [
     "dist",
+    "src/**/*.ts",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/**/*.md",
+    "src/**/*.sql",
     "README.md"
   ],
   "publishConfig": {
@@ -57,7 +62,7 @@
     "typescript": "^5.8.0",
     "vite": "^7.3.2",
     "vitest": "^3.0.0",
-    "@growth-labs/analytics": "0.4.0"
+    "@growth-labs/analytics": "0.4.1"
   },
   "scripts": {
     "build": "tsc",

package/src/client/login-page.ts

@@ -0,0 +1,12 @@
+export function loginPageScript(): string {
+	return `
+    document.querySelectorAll('[data-provider]').forEach(function(el) {
+      el.addEventListener('click', function() {
+        var provider = el.getAttribute('data-provider');
+        if (window.glAnalytics) {
+          window.glAnalytics.track('login_clicked', { provider: provider });
+        }
+      });
+    });
+  `
+}

package/src/cloudflare-workers.d.ts

@@ -0,0 +1,3 @@
+declare module 'cloudflare:workers' {
+	export const env: Record<string, unknown>
+}

package/src/config-store.ts

@@ -0,0 +1,70 @@
+import type { ResolvedAuthOptions } from './options.js'
+import { isEnvMarker, resolveEnvMarker } from './utils/env-marker.js'
+
+let _config: ResolvedAuthOptions | null = null
+
+export function _setConfig(config: ResolvedAuthOptions): void {
+	_config = config
+}
+
+export function getConfig(): ResolvedAuthOptions {
+	const runtimeConfig = (
+		globalThis as typeof globalThis & {
+			__GL_AUTH_CONFIG__?: ResolvedAuthOptions
+		}
+	).__GL_AUTH_CONFIG__
+	const base = runtimeConfig ?? _config
+	if (!base) {
+		throw new Error(
+			'@growth-labs/auth: integration not configured. Add auth() to your astro.config.mjs integrations array.',
+		)
+	}
+	return resolveEnvMarkers(base)
+}
+
+/**
+ * Resolves any `"env:VAR_NAME"` markers on auth-tuple fields against the
+ * runtime env stashed by `src/runtime-bridge.ts`. The bridge is loaded
+ * via `middleware/auth.ts` at module-init time, so by the time any
+ * request reaches `getConfig()` the env is on globalThis. Plain string
+ * values pass through unchanged, preserving backwards compatibility.
+ *
+ * If callers exist that don't go through the auth middleware first AND
+ * the config has markers, we throw a clear error rather than silently
+ * dropping the lookup.
+ */
+function resolveEnvMarkers(base: ResolvedAuthOptions): ResolvedAuthOptions {
+	const env = (
+		globalThis as typeof globalThis & {
+			__GL_AUTH_RUNTIME_ENV__?: Record<string, unknown>
+		}
+	).__GL_AUTH_RUNTIME_ENV__
+	if (env === undefined) {
+		if (anyMarkerPresent(base)) {
+			throw new Error(
+				'@growth-labs/auth: runtime env unavailable for "env:" marker resolution. Ensure the auth middleware ran first (it loads src/runtime-bridge.ts which stashes the env on globalThis).',
+			)
+		}
+		return base
+	}
+	const issuer = resolveEnvMarker(base.issuer, env)
+	if (typeof issuer !== 'string') {
+		throw new Error('@growth-labs/auth: issuer must resolve to a string')
+	}
+	return {
+		...base,
+		issuer,
+		issuerInternal: resolveEnvMarker(base.issuerInternal, env),
+		clientId: resolveEnvMarker(base.clientId, env),
+		resource: resolveEnvMarker(base.resource, env),
+	}
+}
+
+function anyMarkerPresent(base: ResolvedAuthOptions): boolean {
+	return (
+		isEnvMarker(base.issuer) ||
+		isEnvMarker(base.issuerInternal) ||
+		isEnvMarker(base.clientId) ||
+		isEnvMarker(base.resource)
+	)
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+import { _setConfig } from './config-store.js'
+import type { AuthOptions } from './options.js'
+import { authOptionsSchema } from './options.js'
+import type { AuthRenderers } from './types.js'
+
+interface AstroIntegration {
+	name: string
+	hooks: {
+		'astro:config:setup': (params: {
+			addMiddleware: (opts: { entrypoint: string; order: 'pre' | 'post' }) => void
+			injectRoute: (opts: { pattern: string; entrypoint: string; prerender?: boolean }) => void
+			updateConfig: (config: {
+				vite?: { define?: Record<string, string>; plugins?: unknown[] }
+			}) => void
+		}) => void
+	}
+}
+
+const ENTRYPOINT_EXTENSION = import.meta.url.endsWith('.ts') ? '.ts' : '.js'
+
+function resolveEntrypoint(path: string): string {
+	return decodeURIComponent(new URL(`${path}${ENTRYPOINT_EXTENSION}`, import.meta.url).pathname)
+}
+
+/**
+ * Vite plugin that turns the integration's `renderers` option (per-surface
+ * `{ module, export }` specs) into the `virtual:growth-labs/auth/renderers`
+ * module by emitting REAL static ES imports — NOT a serialized function
+ * body. Static imports are bundleable, tree-shakeable, and immune to the
+ * SSR-transform bug that crashed 0.3.6 (where Vite rewrote `await import()`
+ * inside a `Function.prototype.toString()`-serialized renderer body to
+ * `__vite_ssr_dynamic_import__()`, a helper missing in production bundles).
+ */
+export function renderersPlugin(renderers: AuthRenderers): unknown {
+	return {
+		name: '@growth-labs/auth:renderers',
+		resolveId(id: string) {
+			if (id === 'virtual:growth-labs/auth/renderers') return '\0virtual:growth-labs/auth/renderers'
+		},
+		load(id: string) {
+			if (id !== '\0virtual:growth-labs/auth/renderers') return
+
+			const importLines: string[] = []
+			const mapEntries: string[] = []
+			let n = 0
+			for (const [surface, spec] of Object.entries(renderers)) {
+				if (!isValidRendererSpec(spec)) continue
+				const local = `__gl_auth_renderer_${n++}`
+				importLines.push(
+					`import { ${spec.export} as ${local} } from ${JSON.stringify(spec.module)};`,
+				)
+				mapEntries.push(`  ${JSON.stringify(surface)}: ${local},`)
+			}
+			return [...importLines, 'export const renderers = {', ...mapEntries, '};', ''].join('\n')
+		},
+	}
+}
+
+function isValidRendererSpec(value: unknown): value is { module: string; export: string } {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as { module?: unknown }).module === 'string' &&
+		typeof (value as { export?: unknown }).export === 'string'
+	)
+}
+
+export default function auth(userOptions: AuthOptions): AstroIntegration {
+	const options = authOptionsSchema.parse(userOptions)
+	_setConfig(options)
+	const serializableOptions = { ...options, renderers: {} }
+
+	return {
+		name: '@growth-labs/auth',
+		hooks: {
+			'astro:config:setup': ({ addMiddleware, injectRoute, updateConfig }) => {
+				updateConfig({
+					vite: {
+						define: {
+							'globalThis.__GL_AUTH_CONFIG__': JSON.stringify(serializableOptions),
+						},
+						plugins: [renderersPlugin(options.renderers)],
+					},
+				})
+
+				addMiddleware({
+					entrypoint: resolveEntrypoint('./middleware/auth'),
+					order: 'pre',
+				})
+
+				injectRoute({
+					pattern: options.loginPath,
+					entrypoint: resolveEntrypoint('./routes/login'),
+					prerender: false,
+				})
+
+				injectRoute({
+					pattern: '/logout',
+					entrypoint: resolveEntrypoint('./routes/logout'),
+					prerender: false,
+				})
+
+				injectRoute({
+					pattern: options.callbackPath,
+					entrypoint: resolveEntrypoint('./routes/callback'),
+					prerender: false,
+				})
+
+				if (options.providers.includes('password')) {
+					injectRoute({
+						pattern: options.forgotPasswordPath,
+						entrypoint: resolveEntrypoint('./routes/forgot-password'),
+						prerender: false,
+					})
+
+					injectRoute({
+						pattern: options.resetPasswordPath,
+						entrypoint: resolveEntrypoint('./routes/reset-password'),
+						prerender: false,
+					})
+
+					injectRoute({
+						pattern: options.passwordVerifyPath,
+						entrypoint: resolveEntrypoint('./routes/api/password-verify'),
+						prerender: false,
+					})
+
+					injectRoute({
+						pattern: options.passwordResetRequestPath,
+						entrypoint: resolveEntrypoint('./routes/api/password-reset-request'),
+						prerender: false,
+					})
+
+					injectRoute({
+						pattern: options.passwordResetConfirmPath,
+						entrypoint: resolveEntrypoint('./routes/api/password-reset-confirm'),
+						prerender: false,
+					})
+
+					if (options.renderers.password) {
+						injectRoute({
+							pattern: options.passwordPath,
+							entrypoint: resolveEntrypoint('./routes/password'),
+							prerender: false,
+						})
+					}
+				}
+
+				if (options.providers.includes('email-code')) {
+					injectRoute({
+						pattern: options.codeRequestPath,
+						entrypoint: resolveEntrypoint('./routes/api/code-request'),
+						prerender: false,
+					})
+
+					injectRoute({
+						pattern: options.codeVerifyPath,
+						entrypoint: resolveEntrypoint('./routes/api/code-verify'),
+						prerender: false,
+					})
+
+					if (options.renderers.verifyCode) {
+						injectRoute({
+							pattern: options.verifyCodePath,
+							entrypoint: resolveEntrypoint('./routes/verify-code'),
+							prerender: false,
+						})
+					}
+				}
+			},
+		},
+	}
+}

package/src/middleware/auth.ts

@@ -0,0 +1,88 @@
+import { getConfig } from '../config-store.js'
+import '../runtime-bridge.js'
+import type { User } from '../types.js'
+import { resolveClientSecret } from '../utils/client-secret.js'
+import { getCookie, setTokenCookies } from '../utils/cookies.js'
+import { resolveInternalIssuer } from '../utils/issuer.js'
+import { refreshTokens, verifyAccessToken } from '../utils/tokens.js'
+
+export async function onRequest(
+	context: { request: Request; url: URL; locals: Record<string, unknown> },
+	next: () => Promise<Response>,
+): Promise<Response> {
+	const options = getConfig()
+	const issuer = resolveInternalIssuer(options)
+	const { request } = context
+
+	// 1. Read tokens from cookies
+	const accessToken = getCookie(request, `${options.cookiePrefix}_at`)
+	const refreshToken = getCookie(request, `${options.cookiePrefix}_rt`)
+
+	// 2. Attempt to authenticate
+	let user: User | null = null
+	let refreshed: Awaited<ReturnType<typeof refreshTokens>> = null
+
+	if (accessToken) {
+		const verified = await verifyAccessToken(issuer, accessToken)
+		if (verified) {
+			user = {
+				id: verified.sub,
+				email: verified.email,
+				name: verified.name ?? null,
+				avatarUrl: verified.image ?? null,
+			}
+		}
+	}
+
+	if (!user && refreshToken) {
+		const clientId = options.clientId || context.url.hostname
+		const clientSecret = resolveClientSecret(options.clientSecret)
+		refreshed = await refreshTokens(issuer, refreshToken, clientId, clientSecret, options.resource)
+		if (refreshed) {
+			user = {
+				id: refreshed.claims.sub,
+				email: refreshed.claims.email,
+				name: refreshed.claims.name ?? null,
+				avatarUrl: refreshed.claims.image ?? null,
+			}
+		}
+	}
+
+	// 3. Populate context.locals.user
+	context.locals.user = user
+
+	// 4. Gate protected paths
+	if (!user && isGatedPath(context.url.pathname, options.gatedPaths)) {
+		const loginUrl = new URL(
+			`${options.loginPath}?redirect=${encodeURIComponent(context.url.pathname)}`,
+			context.url.origin,
+		)
+		return Response.redirect(loginUrl.toString(), 302)
+	}
+
+	// 5. Continue to the page
+	const response = await next()
+
+	// 6. If tokens were refreshed, set new cookies on the response
+	if (refreshed) {
+		const modifiedResponse = new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: new Headers(response.headers),
+		})
+		setTokenCookies(modifiedResponse, options, refreshed.accessToken, refreshed.refreshToken)
+		return modifiedResponse
+	}
+
+	return response
+}
+
+function isGatedPath(pathname: string, gatedPaths: string[]): boolean {
+	return gatedPaths.some((pattern) => {
+		if (pattern.endsWith('/*')) {
+			const prefix = pattern.slice(0, -1) // '/premium/*' → '/premium/'
+			return pathname.startsWith(prefix)
+		}
+		return pathname === pattern
+	})
+}

package/src/options.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod'
+import type { AuthRenderers } from './types.js'
+
+// String accepted as either a literal URL or an "env:VAR_NAME" marker that
+// gets resolved against the Worker runtime env at request time. See
+// `src/utils/env-marker.ts` and `src/config-store.ts`. Bare "env:" (no
+// binding name) is rejected — it can never resolve to anything useful.
+const urlOrEnvMarker = z
+	.string()
+	.refine((v) => (v.startsWith('env:') && v.length > 4) || /^https?:\/\//i.test(v), {
+		message: 'Must be a URL (https?://...) or an "env:VAR_NAME" marker',
+	})
+
+// String that, if shaped as an "env:VAR_NAME" marker, must include a
+// non-empty binding name. Literal values pass through unconstrained
+// (they can be any string, e.g. OAuth client IDs). A literal value that
+// happens to start with the reserved "env:" prefix will be treated as a
+// marker — pick a non-colliding name in that edge case.
+const stringOrEnvMarker = z.string().refine((v) => !v.startsWith('env:') || v.length > 4, {
+	message: '"env:" marker must include a binding name (e.g. "env:AUTH_CLIENT_ID")',
+})
+
+export const authOptionsSchema = z.object({
+	// ─── Issuer URLs ───
+	issuer: urlOrEnvMarker,
+	issuerInternal: urlOrEnvMarker.optional(),
+
+	// ─── Client identity ───
+	clientId: stringOrEnvMarker.optional(),
+	clientSecret: z.string().optional(),
+	resource: urlOrEnvMarker.optional(),
+
+	// ─── Cookie configuration ───
+	cookiePrefix: z.string(),
+	sessionCookieDomain: z.string().optional(),
+
+	// ─── Token lifetimes ───
+	accessTokenMaxAge: z.number().default(900),
+	refreshTokenMaxAge: z.number().default(2592000),
+
+	// ─── Path configuration ───
+	gatedPaths: z.array(z.string()).default([]),
+	loginPath: z.string().default('/login'),
+	logoutRedirect: z.string().default('/'),
+	callbackPath: z.string().default('/api/auth/callback'),
+	passwordPath: z.string().default('/password'),
+	verifyCodePath: z.string().default('/verify-code'),
+	forgotPasswordPath: z.string().default('/forgot-password'),
+	resetPasswordPath: z.string().default('/reset-password'),
+	passwordVerifyPath: z.string().default('/api/auth/password/verify'),
+	codeRequestPath: z.string().default('/api/auth/code/request'),
+	codeVerifyPath: z.string().default('/api/auth/code/verify'),
+	passwordResetRequestPath: z.string().default('/api/auth/password/reset/request'),
+	passwordResetConfirmPath: z.string().default('/api/auth/password/reset/confirm'),
+
+	// ─── Providers ───
+	providers: z
+		.array(z.enum(['google', 'password', 'email-code']))
+		.default(['google', 'password', 'email-code']),
+
+	// ─── Login page customization ───
+	loginPage: z
+		.object({
+			title: z.string().default('Sign in'),
+			brandName: z.string().optional(),
+			logoUrl: z.string().optional(),
+		})
+		.default({}),
+
+	// ─── Consumer-owned UI renderers ───
+	renderers: z.custom<AuthRenderers>().default({}),
+})
+
+export type AuthOptions = z.input<typeof authOptionsSchema>
+export type ResolvedAuthOptions = z.output<typeof authOptionsSchema>

package/src/renderers.ts

@@ -0,0 +1,182 @@
+import { renderers as bundledRenderers } from 'virtual:growth-labs/auth/renderers'
+import type {
+	AuthRendererBrand,
+	AuthRendererResult,
+	ForgotPasswordRendererPayload,
+	LoginRendererPayload,
+	PasswordRendererPayload,
+	ResetPasswordRendererPayload,
+	ResolvedAuthRenderers,
+	VerifyCodeRendererPayload,
+} from './types.js'
+
+/**
+ * Look up the bundled renderer for a surface. After 0.3.7 the lookup is
+ * build-time only — renderers are resolved into the virtual module by the
+ * Vite plugin via real static `import` statements. The runtime fallback
+ * that previously read `options.renderers?.[surface]` is gone; it could
+ * never have worked in production (functions captured in `astro.config.mjs`
+ * don't survive serialization), and the new `AuthRenderers` shape is a
+ * `{ module, export }` spec rather than a function anyway.
+ */
+export function getRenderer<K extends keyof ResolvedAuthRenderers>(
+	surface: K,
+): ResolvedAuthRenderers[K] | undefined {
+	return bundledRenderers[surface]
+}
+
+export async function renderHtmlResponse(result: AuthRendererResult): Promise<Response> {
+	const rendered = await result
+	if (rendered instanceof Response) {
+		return rendered
+	}
+	return new Response(rendered, {
+		headers: { 'Content-Type': 'text/html; charset=utf-8' },
+	})
+}
+
+export function rendererBrand(options: {
+	loginPage: { title: string; brandName?: string; logoUrl?: string }
+}): AuthRendererBrand {
+	return {
+		title: options.loginPage.title,
+		brandName: options.loginPage.brandName ?? '',
+		logoUrl: options.loginPage.logoUrl ?? '',
+	}
+}
+
+export function loginRendererPayload(
+	options: {
+		loginPage: { title: string; brandName?: string; logoUrl?: string }
+		loginPath: string
+		passwordPath: string
+		verifyCodePath: string
+		providers: string[]
+	},
+	data: {
+		redirectPath: string
+		error: string | null
+		reset: string | null
+		useLocalPassword?: boolean
+		useLocalVerifyCode?: boolean
+	},
+): LoginRendererPayload {
+	const makeLoginStartUrl = (provider: string) =>
+		`${options.loginPath}?provider=${encodeURIComponent(provider)}&redirect=${encodeURIComponent(data.redirectPath)}`
+	const makeSurfaceUrl = (path: string) =>
+		`${path}?redirect=${encodeURIComponent(data.redirectPath)}`
+
+	return {
+		providerUrls: {
+			google: options.providers.includes('google') ? makeLoginStartUrl('google') : undefined,
+			password: options.providers.includes('password')
+				? data.useLocalPassword
+					? makeSurfaceUrl(options.passwordPath)
+					: makeLoginStartUrl('password')
+				: undefined,
+			emailCode: options.providers.includes('email-code')
+				? data.useLocalVerifyCode
+					? makeSurfaceUrl(options.verifyCodePath)
+					: makeLoginStartUrl('email-code')
+				: undefined,
+		},
+		errorCode: data.error ?? undefined,
+		reset: data.reset ? true : undefined,
+		redirect: data.redirectPath,
+		brand: rendererBrand(options),
+	}
+}
+
+export function forgotPasswordRendererPayload(
+	options: {
+		loginPage: { title: string; brandName?: string; logoUrl?: string }
+		loginPath: string
+		passwordResetRequestPath: string
+	},
+	data: {
+		forgotPasswordUrl: string
+		error: string | null
+		sent: string | null
+	},
+): ForgotPasswordRendererPayload {
+	return {
+		forgotPasswordUrl: data.forgotPasswordUrl,
+		passwordResetRequestUrl: options.passwordResetRequestPath,
+		errorCode: data.error ?? undefined,
+		sent: data.sent ? true : undefined,
+		loginUrl: options.loginPath,
+		brand: rendererBrand(options),
+	}
+}
+
+export function resetPasswordRendererPayload(
+	options: {
+		loginPage: { title: string; brandName?: string; logoUrl?: string }
+		loginPath: string
+		passwordResetConfirmPath: string
+	},
+	data: {
+		resetPasswordUrl: string
+		error: string | null
+		token: string | null
+	},
+): ResetPasswordRendererPayload {
+	return {
+		resetPasswordUrl: data.resetPasswordUrl,
+		passwordResetConfirmUrl: options.passwordResetConfirmPath,
+		errorCode: data.error ?? undefined,
+		token: data.token ?? undefined,
+		loginUrl: options.loginPath,
+		brand: rendererBrand(options),
+	}
+}
+
+export function passwordRendererPayload(
+	options: {
+		loginPage: { title: string; brandName?: string; logoUrl?: string }
+		loginPath: string
+		forgotPasswordPath: string
+		passwordVerifyPath: string
+	},
+	data: {
+		email: string | null
+		error: string | null
+		redirectPath: string
+	},
+): PasswordRendererPayload {
+	return {
+		passwordVerifyUrl: options.passwordVerifyPath,
+		forgotPasswordUrl: options.forgotPasswordPath,
+		email: data.email ?? undefined,
+		errorCode: data.error ?? undefined,
+		redirect: data.redirectPath,
+		loginUrl: options.loginPath,
+		brand: rendererBrand(options),
+	}
+}
+
+export function verifyCodeRendererPayload(
+	options: {
+		loginPage: { title: string; brandName?: string; logoUrl?: string }
+		loginPath: string
+		codeRequestPath: string
+		codeVerifyPath: string
+	},
+	data: {
+		email: string | null
+		error: string | null
+		sent: string | null
+		redirectPath: string
+	},
+): VerifyCodeRendererPayload {
+	return {
+		codeRequestUrl: options.codeRequestPath,
+		codeVerifyUrl: options.codeVerifyPath,
+		email: data.email ?? undefined,
+		errorCode: data.error ?? undefined,
+		sent: data.sent ? true : undefined,
+		redirect: data.redirectPath,
+		loginUrl: options.loginPath,
+		brand: rendererBrand(options),
+	}
+}

package/src/routes/api/code-request.ts

@@ -0,0 +1,33 @@
+import {
+	authClient,
+	getConfig,
+	type RouteContext,
+	readForm,
+	readFormString,
+	rejectCrossSitePost,
+	statusRedirect,
+} from './shared.js'
+
+export async function POST(context: RouteContext): Promise<Response> {
+	const crossSitePost = rejectCrossSitePost(context)
+	if (crossSitePost) return crossSitePost
+
+	const options = getConfig()
+	if (!options.providers.includes('email-code')) {
+		return new Response('Not found', { status: 404 })
+	}
+
+	const form = await readForm(context)
+	const email = await readFormString(form, 'email')
+	const redirect = form.get('redirect')?.toString()
+	const result = await authClient(context).code.request({ email })
+
+	return statusRedirect(
+		context,
+		result,
+		options.verifyCodePath,
+		{ email, sent: '1', redirect },
+		options.verifyCodePath,
+		{ email, redirect },
+	)
+}