@growth-labs/auth 0.6.2 → 0.7.1

package/src/types.ts

@@ -0,0 +1,158 @@
+export interface User {
+	id: string
+	email: string
+	name?: string | null
+	avatarUrl?: string | null
+}
+
+export type AuthenticatedUser = User
+export type UnauthenticatedUser = null
+
+export interface AuthRendererBrand {
+	title: string
+	brandName: string
+	logoUrl: string
+}
+
+export interface LoginRendererPayload {
+	providerUrls: {
+		google?: string
+		password?: string
+		emailCode?: string
+	}
+	errorCode?: 'auth_failed' | 'session_expired' | string
+	reset?: boolean
+	redirect: string
+	brand: AuthRendererBrand
+}
+
+export interface ForgotPasswordRendererPayload {
+	forgotPasswordUrl: string
+	passwordResetRequestUrl: string
+	errorCode?: string
+	sent?: boolean
+	loginUrl: string
+	brand: AuthRendererBrand
+}
+
+export interface ResetPasswordRendererPayload {
+	resetPasswordUrl: string
+	passwordResetConfirmUrl: string
+	errorCode?: string
+	token?: string
+	loginUrl: string
+	brand: AuthRendererBrand
+}
+
+export interface PasswordRendererPayload {
+	passwordVerifyUrl: string
+	forgotPasswordUrl: string
+	email?: string
+	errorCode?: string
+	redirect: string
+	loginUrl: string
+	brand: AuthRendererBrand
+}
+
+export interface VerifyCodeRendererPayload {
+	codeRequestUrl: string
+	codeVerifyUrl: string
+	email?: string
+	errorCode?: string
+	sent?: boolean
+	redirect: string
+	loginUrl: string
+	brand: AuthRendererBrand
+}
+
+export interface EmailCodeConfirmRendererPayload {
+	loginUrl: string
+	brand: AuthRendererBrand
+}
+
+export type AuthRendererResult = string | Response | Promise<string | Response>
+
+export type LoginRenderer = (payload: LoginRendererPayload) => AuthRendererResult
+export type ForgotPasswordRenderer = (payload: ForgotPasswordRendererPayload) => AuthRendererResult
+export type ResetPasswordRenderer = (payload: ResetPasswordRendererPayload) => AuthRendererResult
+export type PasswordRenderer = (payload: PasswordRendererPayload) => AuthRendererResult
+export type VerifyCodeRenderer = (payload: VerifyCodeRendererPayload) => AuthRendererResult
+export type EmailCodeConfirmRenderer = (
+	payload: EmailCodeConfirmRendererPayload,
+) => AuthRendererResult
+
+/**
+ * A renderer registration for the `renderers` integration option.
+ *
+ * `module` is an ES module specifier resolvable by the consumer's bundler
+ * (path alias, package name, or relative path). `export` is the named
+ * export within that module that holds the renderer function. The Vite
+ * plugin emits a real static `import { <export> as <local> } from <module>`
+ * at the top of the virtual `virtual:growth-labs/auth/renderers` module,
+ * which makes the renderer fully bundleable and tree-shakeable in
+ * production. **Do not pass an inline async function** — that approach
+ * (via `Function.prototype.toString()`) crashed in production bundles in
+ * 0.3.6 because Vite's SSR transform rewrote dynamic imports inside the
+ * serialized body to `__vite_ssr_dynamic_import__()`, a helper that does
+ * not exist in production bundles. See `MIGRATION.md`.
+ */
+export interface AuthRendererSpec {
+	module: string
+	export: string
+}
+
+export interface AuthRenderers {
+	login?: AuthRendererSpec
+	forgotPassword?: AuthRendererSpec
+	resetPassword?: AuthRendererSpec
+	password?: AuthRendererSpec
+	verifyCode?: AuthRendererSpec
+	emailCodeConfirm?: AuthRendererSpec
+}
+
+/**
+ * The shape of `virtual:growth-labs/auth/renderers` after the plugin
+ * resolves all registered specs into static ES imports. Internal — only
+ * the package's own routes import from this virtual module.
+ */
+export interface ResolvedAuthRenderers {
+	login?: LoginRenderer
+	forgotPassword?: ForgotPasswordRenderer
+	resetPassword?: ResetPasswordRenderer
+	password?: PasswordRenderer
+	verifyCode?: VerifyCodeRenderer
+	emailCodeConfirm?: EmailCodeConfirmRenderer
+}
+
+export interface TokenRefreshResult {
+	accessToken: string
+	refreshToken: string
+	claims: {
+		sub: string
+		email: string
+		name?: string | null
+		image?: string
+	}
+}
+
+export interface TokenExchangeResult {
+	accessToken: string
+	refreshToken: string
+	isNewUser: boolean
+	provider: 'google' | 'password' | 'email-code' | 'unknown'
+	claims: {
+		sub: string
+		email: string
+		name?: string | null
+		image?: string
+	}
+}
+
+// Augment Astro's locals
+declare global {
+	namespace App {
+		interface Locals {
+			user: User | null
+		}
+	}
+}

package/src/utils/analytics.ts

@@ -0,0 +1,56 @@
+type TrackFn = (context: unknown, event: string, props?: Record<string, unknown>) => Promise<void>
+
+let trackFn: TrackFn | null = null
+let resolved = false
+const ANALYTICS_UTILS_MODULE = '@growth-labs/analytics/utils'
+
+async function importOptionalModule(modulePath: string): Promise<Record<string, unknown> | null> {
+	try {
+		return (await import(/* @vite-ignore */ modulePath)) as Record<string, unknown>
+	} catch {
+		return null
+	}
+}
+
+async function resolveAnalytics(): Promise<void> {
+	if (resolved) return
+	resolved = true
+	const mod = await importOptionalModule(ANALYTICS_UTILS_MODULE)
+	let candidate: unknown
+	try {
+		candidate = mod?.trackServerEvent
+	} catch {
+		candidate = undefined
+	}
+	if (typeof candidate === 'function') {
+		trackFn = candidate as TrackFn
+	}
+}
+
+export async function emitAuthEvent(
+	context: unknown,
+	eventName: string,
+	data: Record<string, unknown>,
+): Promise<void> {
+	await resolveAnalytics()
+	if (!trackFn) return
+	return trackFn(context, eventName, data)
+}
+
+export function analyticsAvailable(context: { locals?: Record<string, unknown> }): boolean {
+	void context
+	return true
+}
+
+export async function trackAuthEvent(
+	context: unknown,
+	eventName: string,
+	data: Record<string, unknown> = {},
+): Promise<void> {
+	return emitAuthEvent(context, eventName, data)
+}
+
+export function _resetAnalytics(): void {
+	trackFn = null
+	resolved = false
+}

package/src/utils/client-secret.ts

@@ -0,0 +1,21 @@
+import { getRuntimeEnv } from '../runtime.js'
+
+export function resolveClientSecret(clientSecret?: string): string | undefined {
+	if (!clientSecret) return undefined
+
+	const runtimeValue = getRuntimeEnv()[clientSecret]
+	if (typeof runtimeValue === 'string' && runtimeValue.length > 0) {
+		return runtimeValue
+	}
+
+	return clientSecret
+}
+
+export function createClientSecretBasicAuthHeader(clientId: string, clientSecret: string): string {
+	return `Basic ${btoa(`${formEncode(clientId)}:${formEncode(clientSecret)}`)}`
+}
+
+function formEncode(value: string): string {
+	const params = new URLSearchParams({ value })
+	return params.toString().slice('value='.length)
+}

package/src/utils/cookies.ts

@@ -0,0 +1,134 @@
+import type { ResolvedAuthOptions } from '../options.js'
+
+export interface CookieAttributes {
+	path?: string
+	maxAge?: number
+	httpOnly?: boolean
+	secure?: boolean
+	sameSite?: 'strict' | 'lax' | 'none'
+	domain?: string
+}
+
+const IDENTITY_COOKIE_NAME = 'gl_id'
+const IDENTITY_COOKIE_MAX_AGE = 2592000
+
+export function getCookie(request: Request, name: string): string | null {
+	const header = request.headers.get('cookie')
+	if (!header) return null
+	const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+	return match ? decodeURIComponent(match[1]) : null
+}
+
+export function setCookie(
+	response: Response,
+	name: string,
+	value: string,
+	attributes: CookieAttributes = {},
+): void {
+	const parts = [`${name}=${encodeURIComponent(value)}`]
+	if (attributes.path) parts.push(`Path=${attributes.path}`)
+	if (attributes.maxAge !== undefined) parts.push(`Max-Age=${attributes.maxAge}`)
+	if (attributes.httpOnly) parts.push('HttpOnly')
+	if (attributes.secure) parts.push('Secure')
+	if (attributes.sameSite) parts.push(`SameSite=${attributes.sameSite}`)
+	if (attributes.domain) parts.push(`Domain=${attributes.domain}`)
+	response.headers.append('Set-Cookie', parts.join('; '))
+}
+
+export function clearCookie(response: Response, name: string, domain?: string, path = '/'): void {
+	setCookie(response, name, '', {
+		path,
+		maxAge: 0,
+		...(domain && { domain }),
+	})
+}
+
+export function setIdentityCookie(response: Response, value: string): void {
+	setCookie(response, IDENTITY_COOKIE_NAME, value, {
+		path: '/',
+		maxAge: IDENTITY_COOKIE_MAX_AGE,
+		httpOnly: true,
+		secure: true,
+		sameSite: 'lax',
+	})
+}
+
+export function clearIdentityCookie(response: Response): void {
+	setCookie(response, IDENTITY_COOKIE_NAME, '', {
+		path: '/',
+		maxAge: 0,
+		httpOnly: true,
+		secure: true,
+		sameSite: 'lax',
+	})
+}
+
+export function setTokenCookies(
+	response: Response,
+	options: ResolvedAuthOptions,
+	accessToken: string,
+	refreshToken: string,
+): void {
+	const base: CookieAttributes = {
+		path: '/',
+		httpOnly: true,
+		secure: true,
+		sameSite: 'lax',
+		...(options.sessionCookieDomain && { domain: options.sessionCookieDomain }),
+	}
+	setCookie(response, `${options.cookiePrefix}_at`, accessToken, {
+		...base,
+		maxAge: options.accessTokenMaxAge,
+	})
+	setCookie(response, `${options.cookiePrefix}_rt`, refreshToken, {
+		...base,
+		maxAge: options.refreshTokenMaxAge,
+	})
+}
+
+export function clearTokenCookies(response: Response, options: ResolvedAuthOptions): void {
+	clearCookie(response, `${options.cookiePrefix}_at`, options.sessionCookieDomain)
+	clearCookie(response, `${options.cookiePrefix}_rt`, options.sessionCookieDomain)
+}
+
+export function clearAuthFlowCookies(response: Response, options: ResolvedAuthOptions): void {
+	clearCookie(response, `${options.cookiePrefix}_pkce`, undefined, options.callbackPath)
+	clearCookie(response, `${options.cookiePrefix}_pkce`)
+	clearCookie(response, `${options.cookiePrefix}_state`)
+	clearCookie(response, `${options.cookiePrefix}_redirect`)
+	clearCookie(response, `${options.cookiePrefix}_provider`)
+	clearCookie(response, `${options.cookiePrefix}_auth_path`)
+}
+
+export function setAuthFlowCookies(
+	response: Response,
+	options: ResolvedAuthOptions,
+	verifier: string,
+	state: string,
+	redirectPath: string,
+	provider?: string,
+	flowOptions: { pkcePath?: string; additionalPkcePaths?: string[] } = {},
+): void {
+	const baseAttrs: CookieAttributes = {
+		path: '/',
+		httpOnly: true,
+		secure: true,
+		sameSite: 'lax',
+		maxAge: 600,
+	}
+	const pkcePaths = new Set([
+		flowOptions.pkcePath ?? options.callbackPath,
+		...(flowOptions.additionalPkcePaths ?? []),
+	])
+	for (const path of pkcePaths) {
+		setCookie(response, `${options.cookiePrefix}_pkce`, verifier, {
+			...baseAttrs,
+			path,
+		})
+	}
+	setCookie(response, `${options.cookiePrefix}_state`, state, baseAttrs)
+	setCookie(response, `${options.cookiePrefix}_redirect`, redirectPath, baseAttrs)
+	if (provider) {
+		setCookie(response, `${options.cookiePrefix}_provider`, provider, baseAttrs)
+	}
+}

package/src/utils/encoding.ts

@@ -0,0 +1,5 @@
+export function base64url(bytes: Uint8Array): string {
+	let binary = ''
+	for (const byte of bytes) binary += String.fromCharCode(byte)
+	return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}

package/src/utils/env-marker.ts

@@ -0,0 +1,39 @@
+const ENV_MARKER_PREFIX = 'env:'
+
+/**
+ * Pure resolver: takes an `"env:VAR_NAME"` marker and an env bag, returns
+ * the bound value or throws when the binding is missing / empty. Plain
+ * strings pass through unchanged. Kept pure (no `cloudflare:workers`
+ * import) so `src/config-store.ts` — and therefore the package main entry
+ * — stays clear of the runtime-only specifier and the pure-Node import
+ * gate stays green.
+ *
+ * The runtime env is supplied at call sites (middleware/routes) which can
+ * pull from `cloudflare:workers` themselves, OR by `src/runtime-bridge.ts`
+ * which stashes it onto `globalThis.__GL_AUTH_RUNTIME_ENV__` for
+ * `getConfig()` to read implicitly.
+ */
+export function resolveEnvMarker(
+	value: string | undefined,
+	env: Record<string, unknown>,
+): string | undefined {
+	if (typeof value !== 'string') return value
+	if (!value.startsWith(ENV_MARKER_PREFIX)) return value
+	const name = value.slice(ENV_MARKER_PREFIX.length)
+	if (!name) {
+		throw new Error(
+			'@growth-labs/auth: "env:" marker missing binding name (expected "env:VAR_NAME")',
+		)
+	}
+	const resolved = env[name]
+	if (typeof resolved !== 'string' || resolved.length === 0) {
+		throw new Error(
+			`@growth-labs/auth: env:${name} is not set in the Worker runtime env (declared as "env:${name}" in auth() options)`,
+		)
+	}
+	return resolved
+}
+
+export function isEnvMarker(value: unknown): boolean {
+	return typeof value === 'string' && value.startsWith(ENV_MARKER_PREFIX)
+}

package/src/utils/identity-cookie.ts

@@ -0,0 +1,138 @@
+import { base64url } from './encoding.js'
+
+const SECRET_BYTES = 32
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export type IdentityCookieVerification = { valid: true; payload: string } | { valid: false }
+
+export async function signIdentityCookie(payload: string, secret: string): Promise<string> {
+	if (!payload) {
+		throw new Error('identity cookie payload is required')
+	}
+
+	const payloadBytes = encoder.encode(payload)
+	const key = await importSecret(secret)
+	if (!key) {
+		throw new Error('GL_IDENTITY_SECRET must be a base64-encoded 32-byte secret')
+	}
+
+	const signature = new Uint8Array(
+		await crypto.subtle.sign('HMAC', key, toArrayBuffer(payloadBytes)),
+	)
+	return `${base64url(payloadBytes)}.${base64url(signature)}`
+}
+
+export async function createIdentityCookiePayload(
+	subject: string,
+	secret: string,
+): Promise<string> {
+	if (!subject || !secret) {
+		throw new Error('identity cookie subject and secret are required')
+	}
+
+	const digest = new Uint8Array(
+		await crypto.subtle.digest('SHA-256', encoder.encode(subject + secret)),
+	)
+	return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+export async function verifyIdentityCookie(
+	cookieValue: string,
+	secret: string,
+): Promise<IdentityCookieVerification> {
+	if (!cookieValue || !secret) {
+		return { valid: false }
+	}
+
+	const parts = cookieValue.split('.')
+	if (parts.length !== 2 || !parts[0] || !parts[1]) {
+		return { valid: false }
+	}
+
+	const payloadBytes = decodeBase64Url(parts[0])
+	const signatureBytes = decodeBase64Url(parts[1])
+	const key = await importSecret(secret)
+	if (!payloadBytes || !signatureBytes || !key) {
+		return { valid: false }
+	}
+
+	const expected = new Uint8Array(
+		await crypto.subtle.sign('HMAC', key, toArrayBuffer(payloadBytes)),
+	)
+	if (!timingSafeEqual(expected, signatureBytes)) {
+		return { valid: false }
+	}
+
+	return {
+		valid: true,
+		payload: decoder.decode(payloadBytes),
+	}
+}
+
+export function timingSafeEqual(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
+	const length = Math.max(left.length, right.length)
+	let diff = left.length ^ right.length
+
+	for (let index = 0; index < length; index += 1) {
+		const leftByte = index < left.length ? left[index] : 0
+		const rightByte = index < right.length ? right[index] : 0
+		diff |= leftByte ^ rightByte
+	}
+
+	return diff === 0
+}
+
+async function importSecret(secret: string): Promise<CryptoKey | null> {
+	const bytes = decodeBase64(secret)
+	if (!bytes || bytes.byteLength !== SECRET_BYTES) {
+		return null
+	}
+
+	return crypto.subtle.importKey(
+		'raw',
+		toArrayBuffer(bytes),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	)
+}
+
+function decodeBase64(value: string): Uint8Array | null {
+	const normalized = value.trim().replace(/-/g, '+').replace(/_/g, '/')
+	if (!normalized) {
+		return null
+	}
+
+	try {
+		return binaryStringToBytes(atob(padBase64(normalized)))
+	} catch {
+		return null
+	}
+}
+
+function decodeBase64Url(value: string): Uint8Array | null {
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+		return null
+	}
+
+	return decodeBase64(value)
+}
+
+function padBase64(value: string): string {
+	return value.padEnd(value.length + ((4 - (value.length % 4)) % 4), '=')
+}
+
+function binaryStringToBytes(value: string): Uint8Array {
+	const bytes = new Uint8Array(value.length)
+	for (let index = 0; index < value.length; index += 1) {
+		bytes[index] = value.charCodeAt(index)
+	}
+	return bytes
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+	const buffer = new ArrayBuffer(bytes.byteLength)
+	new Uint8Array(buffer).set(bytes)
+	return buffer
+}