@cloudauth/core 0.1.0

package/src/csrf.ts

@@ -0,0 +1,27 @@
+import { isTrustedOrigin } from './url.js'
+
+/**
+ * Validate that a request's Origin or Referer header matches a trusted origin.
+ * This is a basic CSRF protection for POST endpoints (logout, account linking).
+ */
+export function validateCsrf(request: Request, trustedOrigins: string[]): boolean {
+  // Check Origin header first (more reliable)
+  const origin = request.headers.get('origin')
+  if (origin && isTrustedOrigin(origin, trustedOrigins)) {
+    return true
+  }
+
+  // Fall back to Referer header
+  const referer = request.headers.get('referer')
+  if (referer && isTrustedOrigin(referer, trustedOrigins)) {
+    return true
+  }
+
+  // If no Origin or Referer header, allow through (e.g., server-to-server)
+  // In production, this should be handled by SameSite cookies
+  if (!origin && !referer) {
+    return true
+  }
+
+  return false
+}

package/src/encryption.ts

@@ -0,0 +1,88 @@
+const ALGORITHM = 'AES-GCM'
+const KEY_LENGTH = 256
+const IV_LENGTH = 12
+
+/**
+ * Derive an AES-256-GCM key from a secret using PBKDF2.
+ * This allows using any string as the encryption key.
+ */
+async function deriveKey(secret: string, salt: Uint8Array): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    'PBKDF2',
+    false,
+    ['deriveKey'],
+  )
+
+  return crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt,
+      iterations: 100_000,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    { name: ALGORITHM, length: KEY_LENGTH },
+    false,
+    ['encrypt', 'decrypt'],
+  )
+}
+
+/**
+ * Encrypt a plaintext string using AES-256-GCM.
+ * Returns a base64url-encoded string containing salt + iv + ciphertext.
+ */
+export async function encrypt(plaintext: string, secret: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(16))
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))
+  const key = await deriveKey(secret, salt)
+
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: ALGORITHM, iv },
+    key,
+    new TextEncoder().encode(plaintext),
+  )
+
+  // Combine salt + iv + ciphertext into a single base64url string
+  const combined = new Uint8Array(salt.length + iv.length + ciphertext.byteLength)
+  combined.set(salt, 0)
+  combined.set(iv, salt.length)
+  combined.set(new Uint8Array(ciphertext), salt.length + iv.length)
+
+  return base64url(combined)
+}
+
+/**
+ * Decrypt a base64url-encoded string that was encrypted with encrypt().
+ */
+export async function decrypt(encoded: string, secret: string): Promise<string> {
+  const combined = base64urlDecode(encoded)
+  const salt = combined.slice(0, 16)
+  const iv = combined.slice(16, 16 + IV_LENGTH)
+  const ciphertext = combined.slice(16 + IV_LENGTH)
+
+  const key = await deriveKey(secret, salt)
+
+  const plaintext = await crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext)
+
+  return new TextDecoder().decode(plaintext)
+}
+
+function base64url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+function base64urlDecode(str: string): Uint8Array {
+  const base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  const padding = base64.length % 4 === 0 ? '' : '='.repeat(4 - (base64.length % 4))
+  const binary = atob(base64 + padding)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}

package/src/errors.ts

@@ -0,0 +1,65 @@
+export class AuthError extends Error {
+  public readonly code: string
+
+  constructor(code: string, message: string) {
+    super(message)
+    this.name = 'AuthError'
+    this.code = code
+  }
+}
+
+export class OAuthCallbackError extends AuthError {
+  constructor(message: string, code = 'OAUTH_CALLBACK_FAILED') {
+    super(code, message)
+    this.name = 'OAuthCallbackError'
+  }
+}
+
+export class InvalidStateError extends AuthError {
+  constructor(message = 'OAuth state is invalid, expired, or already used') {
+    super('INVALID_STATE', message)
+    this.name = 'InvalidStateError'
+  }
+}
+
+export class ProviderProfileError extends AuthError {
+  constructor(message = 'Failed to fetch provider profile') {
+    super('PROVIDER_PROFILE_FAILED', message)
+    this.name = 'ProviderProfileError'
+  }
+}
+
+export class ProviderUnreachableError extends AuthError {
+  constructor(message = 'Provider is unreachable or timed out') {
+    super('PROVIDER_UNREACHABLE', message)
+    this.name = 'ProviderUnreachableError'
+  }
+}
+
+export class AccountLinkingError extends AuthError {
+  constructor(message: string, code = 'ACCOUNT_LINKING_FAILED') {
+    super(code, message)
+    this.name = 'AccountLinkingError'
+  }
+}
+
+export class SessionExpiredError extends AuthError {
+  constructor(message = 'Session has expired') {
+    super('SESSION_EXPIRED', message)
+    this.name = 'SessionExpiredError'
+  }
+}
+
+export class UnauthorizedError extends AuthError {
+  constructor(message = 'Authentication required') {
+    super('UNAUTHORIZED', message)
+    this.name = 'UnauthorizedError'
+  }
+}
+
+export class ForbiddenCallbackURLError extends AuthError {
+  constructor(message = 'Callback URL is not in trusted origins') {
+    super('INVALID_CALLBACK_URL', message)
+    this.name = 'ForbiddenCallbackURLError'
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,54 @@
+import type { User, Account, Session, ProviderProfile } from './types.js'
+import type { AuthAdapter } from './adapter.js'
+
+export interface HookContext {
+  adapter: AuthAdapter
+  request?: Request
+}
+
+export interface BeforeSignInCtx extends HookContext {
+  profile: ProviderProfile
+}
+
+export interface AfterSignInCtx extends HookContext {
+  session: Session
+  user: User
+  profile: ProviderProfile
+}
+
+export interface OnUserCreatedCtx extends HookContext {
+  user: User
+}
+
+export interface OnAccountLinkedCtx extends HookContext {
+  account: Account
+  user: User
+}
+
+export interface BeforeSessionCreatedCtx extends HookContext {
+  user: User
+}
+
+export interface AfterSessionCreatedCtx extends HookContext {
+  session: Session
+  user: User
+}
+
+export interface BeforeLogoutCtx extends HookContext {
+  session: Session
+}
+
+export interface AfterLogoutCtx extends HookContext {
+  session: Session
+}
+
+export interface HooksConfig {
+  beforeSignIn?: (ctx: BeforeSignInCtx) => Promise<void>
+  afterSignIn?: (ctx: AfterSignInCtx) => Promise<void>
+  onUserCreated?: (ctx: OnUserCreatedCtx) => Promise<void>
+  onAccountLinked?: (ctx: OnAccountLinkedCtx) => Promise<void>
+  beforeSessionCreated?: (ctx: BeforeSessionCreatedCtx) => Promise<void>
+  afterSessionCreated?: (ctx: AfterSessionCreatedCtx) => Promise<void>
+  beforeLogout?: (ctx: BeforeLogoutCtx) => Promise<void>
+  afterLogout?: (ctx: AfterLogoutCtx) => Promise<void>
+}

package/src/http.ts

@@ -0,0 +1,192 @@
+import type { TokenSet, ProviderProfile } from './types.js'
+import { ProviderUnreachableError, ProviderProfileError } from './errors.js'
+
+export interface ProviderHttpOptions {
+  timeout?: number
+  retries?: number
+  retryDelay?: number
+}
+
+const DEFAULT_TIMEOUT = 10_000 // 10 seconds
+const DEFAULT_RETRIES = 0
+const DEFAULT_RETRY_DELAY = 1_000 // 1 second
+
+interface TokenEndpointResponse {
+  access_token?: string
+  refresh_token?: string
+  id_token?: string
+  scope?: string
+  token_type?: string
+  expires_in?: number
+}
+
+interface UserinfoResponse {
+  sub?: string
+  id?: string
+  email?: string
+  email_verified?: boolean
+  name?: string
+  picture?: string
+  provider?: string
+  [key: string]: unknown
+}
+
+async function fetchWithTimeout(
+  url: string,
+  options: RequestInit & { timeout?: number },
+): Promise<Response> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => {
+    controller.abort()
+  }, timeout)
+
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    })
+    return response
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+function isNetworkError(error: unknown): boolean {
+  return (
+    error instanceof TypeError || (error instanceof DOMException && error.name === 'AbortError')
+  )
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+/**
+ * Exchange an authorization code for tokens at the provider's token endpoint.
+ * Uses POST with application/x-www-form-urlencoded body.
+ */
+export async function exchangeCode(
+  tokenEndpoint: string,
+  params: {
+    clientId: string
+    clientSecret: string
+    code: string
+    codeVerifier: string
+    redirectUri: string
+  },
+  options?: ProviderHttpOptions,
+): Promise<TokenSet> {
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT
+  const retries = options?.retries ?? DEFAULT_RETRIES
+  const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY
+
+  const body = new URLSearchParams({
+    client_id: params.clientId,
+    client_secret: params.clientSecret,
+    code: params.code,
+    code_verifier: params.codeVerifier,
+    redirect_uri: params.redirectUri,
+    grant_type: 'authorization_code',
+  })
+
+  let lastError: unknown
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetchWithTimeout(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body,
+        timeout,
+      })
+
+      if (response.ok) {
+        const data = (await response.json()) as TokenEndpointResponse
+        return {
+          accessToken: data.access_token ?? '',
+          refreshToken: data.refresh_token,
+          idToken: data.id_token,
+          scope: data.scope,
+          tokenType: data.token_type,
+          expiresAt: data.expires_in,
+        }
+      }
+
+      // Non-retryable HTTP error
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new ProviderUnreachableError(
+        `Token endpoint returned ${String(response.status)}: ${errorBody}`,
+      )
+    } catch (error) {
+      lastError = error
+
+      // Only retry on network errors, not 4xx/5xx responses
+      if (isNetworkError(error) && attempt < retries) {
+        await sleep(retryDelay)
+        continue
+      }
+
+      throw error
+    }
+  }
+
+  throw lastError
+}
+
+/**
+ * Fetch a provider's user profile from the userinfo endpoint.
+ * The access token is sent as a Bearer token in the Authorization header.
+ */
+export async function fetchProfile(
+  userinfoEndpoint: string,
+  accessToken: string,
+  options?: ProviderHttpOptions,
+): Promise<ProviderProfile> {
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT
+  const retries = options?.retries ?? DEFAULT_RETRIES
+  const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY
+
+  let lastError: unknown
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetchWithTimeout(userinfoEndpoint, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/json',
+        },
+        timeout,
+      })
+
+      if (response.ok) {
+        const data = (await response.json()) as UserinfoResponse
+        return {
+          provider: data.provider ?? '',
+          providerAccountId: data.sub ?? data.id ?? '',
+          email: data.email,
+          emailVerified: data.email_verified,
+          name: data.name,
+          image: data.picture,
+          raw: data,
+        }
+      }
+
+      throw new ProviderProfileError(`Userinfo endpoint returned ${String(response.status)}`)
+    } catch (error) {
+      lastError = error
+
+      if (isNetworkError(error) && attempt < retries) {
+        await sleep(retryDelay)
+        continue
+      }
+
+      throw error
+    }
+  }
+
+  throw lastError
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+// Types
+export type {
+  User,
+  Account,
+  Session,
+  SessionWithUser,
+  OAuthState,
+  ProviderProfile,
+  TokenSet,
+  CreateUserInput,
+  UpdateUserInput,
+  CreateAccountInput,
+  CreateSessionInput,
+  UpdateSessionInput,
+  CreateOAuthStateInput,
+} from './types.js'
+
+// Provider interface
+export type { AuthProvider, AuthorizationParams, ExchangeCodeParams } from './provider.js'
+
+// Adapter interface
+export type { AuthAdapter } from './adapter.js'
+
+// Errors
+export {
+  AuthError,
+  OAuthCallbackError,
+  InvalidStateError,
+  ProviderProfileError,
+  ProviderUnreachableError,
+  AccountLinkingError,
+  SessionExpiredError,
+  UnauthorizedError,
+  ForbiddenCallbackURLError,
+} from './errors.js'
+
+// Additional fields
+export type {
+  AdditionalField,
+  AdditionalFieldsConfig,
+  StringField,
+  BooleanField,
+  NumberField,
+  DateField,
+  InferFieldType,
+  InferAdditionalFields,
+  InferTypes,
+} from './additional-fields.js'
+
+// Hooks
+export type {
+  HookContext,
+  BeforeSignInCtx,
+  AfterSignInCtx,
+  OnUserCreatedCtx,
+  OnAccountLinkedCtx,
+  BeforeSessionCreatedCtx,
+  AfterSessionCreatedCtx,
+  BeforeLogoutCtx,
+  AfterLogoutCtx,
+  HooksConfig,
+} from './hooks.js'
+
+// Config
+export type {
+  SessionConfig,
+  UserConfig,
+  AccountLinkingConfig,
+  SecurityConfig,
+  AuthConfig,
+  CloudAuthInstance,
+} from './config.js'
+
+// Crypto utilities
+export {
+  generateSessionToken,
+  hashToken,
+  generateCodeVerifier,
+  generateCodeChallenge,
+  constantTimeEqual,
+} from './crypto.js'
+
+// Cookie utilities
+export { serializeCookie, parseCookie, signCookie, verifyCookie } from './cookies.js'
+export type { CookieOptions } from './cookies.js'
+
+// URL utilities
+export { isTrustedOrigin, buildCallbackURL } from './url.js'
+
+// Provider HTTP client
+export { exchangeCode, fetchProfile } from './http.js'
+export type { ProviderHttpOptions } from './http.js'
+
+// Rate limiter
+export { inMemoryRateLimiter, defaultRateLimits } from './rate-limiter.js'
+export type { RateLimiter, RateLimitResult } from './rate-limiter.js'
+
+// CSRF protection
+export { validateCsrf } from './csrf.js'
+
+// Token encryption
+export { encrypt, decrypt } from './encryption.js'
+
+// Auth engine
+export {
+  createAuthUrl,
+  handleCallback,
+  getSession as getSessionFromAuth,
+  signOut as signOutFromAuth,
+} from './auth.js'
+export type { AuthResponse } from './auth.js'
+
+// --- cloudAuth function ---
+
+import type { AuthConfig, CloudAuthInstance } from './config.js'
+import {
+  createAuthUrl,
+  handleCallback,
+  getSession as getSessionFromAuth,
+  signOut as signOutFromAuth,
+} from './auth.js'
+
+export function cloudAuth(config: AuthConfig): CloudAuthInstance {
+  // Validate required config
+  if (!config.appName) {
+    throw new Error('cloudAuth: appName is required')
+  }
+  if (!config.baseURL) {
+    throw new Error('cloudAuth: baseURL is required')
+  }
+  /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+  if (!config.providers || config.providers.length === 0) {
+    throw new Error('cloudAuth: at least one provider is required')
+  }
+  if (!config.database) {
+    throw new Error('cloudAuth: database adapter is required')
+  }
+  /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+
+  return {
+    $Infer: {} as CloudAuthInstance['$Infer'],
+
+    createAuthUrl(providerId: string, request?: Request): Promise<URL> {
+      return createAuthUrl(config, providerId, request)
+    },
+
+    handleCallback(providerId: string, request: Request) {
+      return handleCallback(config, providerId, request, config.hooks)
+    },
+
+    getSession(request: Request) {
+      return getSessionFromAuth(config, request)
+    },
+
+    signOut(request: Request) {
+      return signOutFromAuth(config, request, config.hooks)
+    },
+  }
+}
+
+export const version = '0.0.1'

package/src/provider.ts

@@ -0,0 +1,21 @@
+import type { ProviderProfile, TokenSet } from './types.js'
+
+export interface AuthorizationParams {
+  state: string
+  codeVerifier: string
+  redirectUri: string
+}
+
+export interface ExchangeCodeParams {
+  code: string
+  codeVerifier: string
+  redirectUri: string
+}
+
+export interface AuthProvider {
+  id: string
+  type: 'oauth' | 'oidc'
+  authorizationUrl(params: AuthorizationParams): URL
+  exchangeCode(params: ExchangeCodeParams): Promise<TokenSet>
+  getProfile(tokens: TokenSet): Promise<ProviderProfile>
+}

package/src/rate-limiter.ts

@@ -0,0 +1,64 @@
+export interface RateLimitResult {
+  allowed: boolean
+  remaining: number
+  resetAt: Date
+}
+
+export interface RateLimiter {
+  check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>
+}
+
+interface WindowEntry {
+  timestamps: number[]
+}
+
+/**
+ * In-memory sliding window rate limiter.
+ * Suitable for single-instance development, NOT for production multi-instance use.
+ * For production, provide a Redis/D1-based implementation.
+ */
+export function inMemoryRateLimiter(): RateLimiter {
+  const windows = new Map<string, WindowEntry>()
+
+  return {
+    check(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+      return new Promise((resolve) => {
+        const now = Date.now()
+        let entry = windows.get(key)
+
+        if (!entry) {
+          entry = { timestamps: [] }
+          windows.set(key, entry)
+        }
+
+        // Remove timestamps outside the current window
+        const active = entry.timestamps.filter((ts) => now - ts < windowMs)
+        entry.timestamps = active
+
+        if (active.length >= limit) {
+          const oldest = active[0] ?? now
+          resolve({
+            allowed: false,
+            remaining: 0,
+            resetAt: new Date(oldest + windowMs),
+          })
+          return
+        }
+
+        active.push(now)
+        resolve({
+          allowed: true,
+          remaining: limit - active.length,
+          resetAt: new Date(now + windowMs),
+        })
+      })
+    },
+  }
+}
+
+export const defaultRateLimits = {
+  signIn: { limit: 10, windowMs: 60_000 },
+  callback: { limit: 20, windowMs: 60_000 },
+  logout: { limit: 30, windowMs: 60_000 },
+  linkAccount: { limit: 5, windowMs: 60_000 },
+} as const