@cloudauth/core 0.1.0

package/src/adapter.ts

@@ -0,0 +1,39 @@
+import type {
+  User,
+  Account,
+  Session,
+  SessionWithUser,
+  OAuthState,
+  CreateUserInput,
+  UpdateUserInput,
+  CreateAccountInput,
+  CreateSessionInput,
+  UpdateSessionInput,
+  CreateOAuthStateInput,
+} from './types.js'
+
+export interface AuthAdapter {
+  // User operations
+  createUser(data: CreateUserInput): Promise<User>
+  getUserById(id: string): Promise<User | null>
+  getUserByEmail(email: string): Promise<User | null>
+  updateUser(id: string, data: UpdateUserInput): Promise<User>
+
+  // Account operations
+  createAccount(data: CreateAccountInput): Promise<Account>
+  getAccount(provider: string, providerAccountId: string): Promise<Account | null>
+  getAccountsByUserId(userId: string): Promise<Account[]>
+  linkAccount(userId: string, data: CreateAccountInput): Promise<Account>
+  deleteAccount(accountId: string): Promise<void>
+
+  // Session operations
+  createSession(data: CreateSessionInput): Promise<Session>
+  getSessionByTokenHash(tokenHash: string): Promise<SessionWithUser | null>
+  updateSession(id: string, data: UpdateSessionInput): Promise<Session>
+  deleteSession(tokenHash: string): Promise<void>
+  deleteExpiredSessions(): Promise<void>
+
+  // OAuth state operations
+  createOAuthState(data: CreateOAuthStateInput): Promise<void>
+  consumeOAuthState(stateHash: string): Promise<OAuthState | null>
+}

package/src/additional-fields.ts

@@ -0,0 +1,53 @@
+import type { User } from './types.js'
+
+// --- Field configuration ---
+
+export interface StringField {
+  type: 'string'
+  defaultValue?: string
+  input?: boolean
+}
+
+export interface BooleanField {
+  type: 'boolean'
+  defaultValue?: boolean
+  input?: boolean
+}
+
+export interface NumberField {
+  type: 'number'
+  defaultValue?: number
+  input?: boolean
+}
+
+export interface DateField {
+  type: 'date'
+  defaultValue?: Date
+  input?: boolean
+}
+
+export type AdditionalField = StringField | BooleanField | NumberField | DateField
+
+export type AdditionalFieldsConfig = Record<string, AdditionalField>
+
+// --- Type inference helpers ---
+
+export type InferFieldType<T extends AdditionalField> = T extends StringField
+  ? string
+  : T extends BooleanField
+    ? boolean
+    : T extends NumberField
+      ? number
+      : T extends DateField
+        ? Date
+        : unknown
+
+export type InferAdditionalFields<T extends AdditionalFieldsConfig> = {
+  [K in keyof T]: InferFieldType<T[K]>
+} & {}
+
+// --- $Infer utility ---
+
+export interface InferTypes<TAdditional extends AdditionalFieldsConfig = Record<string, never>> {
+  User: User & InferAdditionalFields<TAdditional>
+}

package/src/auth.ts

@@ -0,0 +1,355 @@
+import type { AuthConfig } from './config.js'
+import type { AuthProvider } from './provider.js'
+import type { SessionWithUser, User, Session } from './types.js'
+import {
+  generateSessionToken,
+  hashToken,
+  generateCodeVerifier,
+  generateCodeChallenge,
+} from './crypto.js'
+import { signCookie, verifyCookie, serializeCookie } from './cookies.js'
+import type { HooksConfig } from './hooks.js'
+import { InvalidStateError } from './errors.js'
+
+export interface AuthResponse {
+  session: Session
+  user: User
+  cookieHeader: string
+}
+
+/**
+ * Generate the authorization URL to redirect the user to the provider.
+ */
+export async function createAuthUrl(
+  config: AuthConfig,
+  providerId: string,
+  _request?: Request,
+): Promise<URL> {
+  const provider = findProvider(config.providers, providerId)
+  const adapter = config.database
+
+  const codeVerifier = generateCodeVerifier()
+  const state = generateSessionToken()
+  const stateHash = await hashToken(state)
+  const codeChallenge = await generateCodeChallenge(codeVerifier)
+
+  const callbackUrl = buildCallbackUrl(config, providerId)
+  const redirectUri = buildRedirectUri(config, providerId)
+
+  // Persist OAuth state for callback validation
+  await adapter.createOAuthState({
+    stateHash,
+    codeVerifier,
+    provider: providerId,
+    callbackUrl,
+    errorUrl: undefined,
+    expiresAt: new Date(Date.now() + 600_000), // 10 minute expiry
+  })
+
+  const authUrl = provider.authorizationUrl({
+    state,
+    codeVerifier: codeChallenge,
+    redirectUri,
+  })
+
+  return authUrl
+}
+
+/**
+ * Handle the OAuth callback from the provider.
+ */
+export async function handleCallback(
+  config: AuthConfig,
+  providerId: string,
+  request: Request,
+  hooks?: HooksConfig,
+): Promise<AuthResponse> {
+  const provider = findProvider(config.providers, providerId)
+  const adapter = config.database
+  const secret = config.security?.secret
+  const sessionConfig = config.session ?? {}
+
+  const url = new URL(request.url)
+  const code = url.searchParams.get('code')
+  const state = url.searchParams.get('state')
+  const error = url.searchParams.get('error')
+
+  // Handle provider error (user denied consent, etc.)
+  if (error) {
+    throw new Error(`Provider returned error: ${error}`)
+  }
+
+  if (!code || !state) {
+    throw new InvalidStateError('Missing code or state parameter')
+  }
+
+  // Validate and consume OAuth state (single-use)
+  const stateHash = await hashToken(state)
+  const storedState = await adapter.consumeOAuthState(stateHash)
+
+  if (!storedState) {
+    throw new InvalidStateError()
+  }
+
+  // Exchange code for tokens
+  const redirectUri = buildRedirectUri(config, providerId)
+  const tokenSet = await provider.exchangeCode({
+    code,
+    codeVerifier: storedState.codeVerifier,
+    redirectUri,
+  })
+
+  // Fetch provider profile
+  const profile = await provider.getProfile(tokenSet)
+
+  // Run beforeSignIn hook (if configured)
+  if (hooks?.beforeSignIn) {
+    await hooks.beforeSignIn({ adapter, profile, request })
+  }
+
+  // Find or create user
+  const existingAccount = await adapter.getAccount(providerId, profile.providerAccountId)
+  let user: User
+
+  if (existingAccount) {
+    // Existing account — get the user
+    const existingUser = await adapter.getUserById(existingAccount.userId)
+    if (!existingUser) {
+      throw new Error('User not found for existing account')
+    }
+    user = existingUser
+  } else {
+    // New account — find or create user by email
+    const existingUser = profile.email ? await adapter.getUserByEmail(profile.email) : null
+
+    if (existingUser) {
+      user = existingUser
+      // Link the new provider account
+      const linkedAccount = await adapter.linkAccount(user.id, {
+        userId: user.id,
+        provider: providerId,
+        providerAccountId: profile.providerAccountId,
+        accessToken: config.security?.storeProviderTokens ? tokenSet.accessToken : null,
+        refreshToken: config.security?.storeProviderTokens ? (tokenSet.refreshToken ?? null) : null,
+        idToken: config.security?.storeProviderTokens ? (tokenSet.idToken ?? null) : null,
+        scope: tokenSet.scope ?? null,
+        tokenType: tokenSet.tokenType ?? null,
+        expiresAt: tokenSet.expiresAt ? new Date(Date.now() + tokenSet.expiresAt * 1000) : null,
+      })
+
+      if (hooks?.onAccountLinked) {
+        await hooks.onAccountLinked({ adapter, user, account: linkedAccount })
+      }
+    } else {
+      // Create new user
+      user = await adapter.createUser({
+        email: profile.email ?? null,
+        emailVerified: profile.emailVerified ?? false,
+        name: profile.name ?? null,
+        image: profile.image ?? null,
+      })
+
+      // Create account
+      await adapter.createAccount({
+        userId: user.id,
+        provider: providerId,
+        providerAccountId: profile.providerAccountId,
+        accessToken: config.security?.storeProviderTokens ? tokenSet.accessToken : null,
+        refreshToken: config.security?.storeProviderTokens ? (tokenSet.refreshToken ?? null) : null,
+        idToken: config.security?.storeProviderTokens ? (tokenSet.idToken ?? null) : null,
+        scope: tokenSet.scope ?? null,
+        tokenType: tokenSet.tokenType ?? null,
+        expiresAt: tokenSet.expiresAt ? new Date(Date.now() + tokenSet.expiresAt * 1000) : null,
+      })
+
+      if (hooks?.onUserCreated) {
+        await hooks.onUserCreated({ adapter, user })
+      }
+    }
+  }
+
+  // Run afterSignIn hook
+  if (hooks?.afterSignIn) {
+    const fakeSession = {
+      id: '',
+      userId: user.id,
+      tokenHash: '',
+      expiresAt: new Date(),
+      ipAddress: null,
+      userAgent: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+    await hooks.afterSignIn({ adapter, session: fakeSession, user, profile })
+  }
+
+  // Create session
+  const sessionToken = generateSessionToken()
+  const tokenHash = await hashToken(sessionToken)
+  const expiresInMs = (sessionConfig.expiresIn ?? 30 * 24 * 60 * 60) * 1000
+
+  if (hooks?.beforeSessionCreated) {
+    await hooks.beforeSessionCreated({ adapter, user })
+  }
+
+  const session = await adapter.createSession({
+    userId: user.id,
+    tokenHash,
+    expiresAt: new Date(Date.now() + expiresInMs),
+    ipAddress: request.headers.get('x-forwarded-for') ?? request.headers.get('x-real-ip') ?? null,
+    userAgent: request.headers.get('user-agent') ?? null,
+  })
+
+  if (hooks?.afterSessionCreated) {
+    await hooks.afterSessionCreated({ adapter, session, user })
+  }
+
+  // Sign the session cookie
+  const cookieName = sessionConfig.cookieName ?? 'cloud_auth_session'
+  const cookieSecret = secret
+  if (!cookieSecret) {
+    throw new Error('cloudAuth: security.secret is required for cookie signing')
+  }
+
+  const signedToken = await signCookie(sessionToken, cookieSecret)
+  const cookieHeader = serializeCookie(cookieName, signedToken, {
+    maxAge: sessionConfig.expiresIn ?? 30 * 24 * 60 * 60,
+    path: '/',
+    secure: sessionConfig.secure ?? true,
+    httpOnly: sessionConfig.httpOnly ?? true,
+    sameSite: sessionConfig.sameSite ?? 'lax',
+  })
+
+  return { session, user, cookieHeader }
+}
+
+/**
+ * Get the current session from a request.
+ * Validates the session cookie, checks expiry, and returns session with user.
+ */
+export async function getSession(
+  config: AuthConfig,
+  request: Request,
+): Promise<SessionWithUser | null> {
+  const adapter = config.database
+  const secret = config.security?.secret
+  const sessionConfig = config.session ?? {}
+  const cookieName = sessionConfig.cookieName ?? 'cloud_auth_session'
+
+  if (!secret) {
+    throw new Error('cloudAuth: security.secret is required')
+  }
+
+  const cookieHeader = request.headers.get('cookie')
+  if (!cookieHeader) return null
+
+  const cookies = parseCookies(cookieHeader)
+  const signedToken = cookies[cookieName]
+  if (!signedToken) return null
+
+  const token = await verifyCookie(signedToken, secret)
+  if (!token) return null
+
+  const tokenHash = await hashToken(token)
+  const sessionWithUser = await adapter.getSessionByTokenHash(tokenHash)
+  if (!sessionWithUser) return null
+
+  // Check expiry
+  if (sessionWithUser.session.expiresAt < new Date()) {
+    await adapter.deleteSession(tokenHash)
+    return null
+  }
+
+  // Rolling expiration
+  const updateAge = sessionConfig.updateAge
+  if (updateAge && sessionWithUser.session.expiresAt.getTime() - Date.now() < updateAge * 1000) {
+    const newExpiresAt = new Date(
+      Date.now() + (sessionConfig.expiresIn ?? 30 * 24 * 60 * 60) * 1000,
+    )
+    await adapter.updateSession(sessionWithUser.session.id, { expiresAt: newExpiresAt })
+    sessionWithUser.session.expiresAt = newExpiresAt
+  }
+
+  return sessionWithUser
+}
+
+/**
+ * Sign out a user by deleting their session and returning a cleared cookie.
+ */
+export async function signOut(
+  config: AuthConfig,
+  request: Request,
+  hooks?: HooksConfig,
+): Promise<string> {
+  const adapter = config.database
+  const secret = config.security?.secret
+  const sessionConfig = config.session ?? {}
+  const cookieName = sessionConfig.cookieName ?? 'cloud_auth_session'
+
+  if (!secret) {
+    throw new Error('cloudAuth: security.secret is required')
+  }
+
+  const cookieHeader = request.headers.get('cookie')
+  if (cookieHeader) {
+    const cookies = parseCookies(cookieHeader)
+    const signedToken = cookies[cookieName]
+
+    if (signedToken) {
+      const token = await verifyCookie(signedToken, secret)
+      if (token) {
+        const tokenHash = await hashToken(token)
+        const sessionWithUser = await adapter.getSessionByTokenHash(tokenHash)
+
+        if (sessionWithUser && hooks?.beforeLogout) {
+          await hooks.beforeLogout({ adapter, session: sessionWithUser.session })
+        }
+
+        await adapter.deleteSession(tokenHash)
+
+        if (sessionWithUser && hooks?.afterLogout) {
+          await hooks.afterLogout({ adapter, session: sessionWithUser.session })
+        }
+      }
+    }
+  }
+
+  return serializeCookie(cookieName, '', {
+    maxAge: 0,
+    path: '/',
+    secure: sessionConfig.secure ?? true,
+    httpOnly: sessionConfig.httpOnly ?? true,
+    sameSite: sessionConfig.sameSite ?? 'lax',
+  })
+}
+
+// --- Internal helpers ---
+
+function findProvider(providers: AuthProvider[], id: string): AuthProvider {
+  const provider = providers.find((p) => p.id === id)
+  if (!provider) {
+    throw new Error(`Provider "${id}" not found`)
+  }
+  return provider
+}
+
+function buildCallbackUrl(config: AuthConfig, providerId: string): string {
+  const base = config.baseURL.replace(/\/+$/, '')
+  return `${base}/auth/${providerId}/callback`
+}
+
+function buildRedirectUri(config: AuthConfig, providerId: string): string {
+  return buildCallbackUrl(config, providerId)
+}
+
+function parseCookies(header: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const pair of header.split(';')) {
+    const idx = pair.indexOf('=')
+    if (idx === -1) continue
+    const name = pair.slice(0, idx).trim()
+    const value = pair.slice(idx + 1).trim()
+    if (name) result[decodeURIComponent(name)] = decodeURIComponent(value)
+  }
+  return result
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+import type { AuthProvider } from './provider.js'
+import type { AuthAdapter } from './adapter.js'
+import type { AdditionalFieldsConfig } from './additional-fields.js'
+import type { HooksConfig } from './hooks.js'
+
+export interface SessionConfig {
+  cookieName?: string
+  expiresIn?: number
+  updateAge?: number
+  sameSite?: 'lax' | 'strict' | 'none'
+  secure?: boolean
+  httpOnly?: boolean
+}
+
+export interface UserConfig {
+  additionalFields?: AdditionalFieldsConfig
+  mapProfileToUser?: (
+    profile: import('./types.js').ProviderProfile,
+  ) => Promise<Record<string, unknown>>
+}
+
+export interface AccountLinkingConfig {
+  enabled?: boolean
+  trustedProviders?: string[]
+  requireVerifiedEmail?: boolean
+  providerTrust?: Record<string, 'high' | 'medium' | 'low'>
+}
+
+export interface SecurityConfig {
+  storeProviderTokens?: boolean
+  encryptProviderTokens?: boolean
+  pkce?: boolean
+  secret?: string
+  providerHttp?: {
+    timeout?: number
+    retries?: number
+    retryDelay?: number
+  }
+}
+
+export interface AuthConfig {
+  appName: string
+  baseURL: string
+  trustedOrigins?: string[]
+  providers: AuthProvider[]
+  database: AuthAdapter
+  session?: SessionConfig
+  user?: UserConfig
+  accountLinking?: AccountLinkingConfig
+  security?: SecurityConfig
+  hooks?: HooksConfig
+}
+
+export interface CloudAuthInstance {
+  $Infer: {
+    User: import('./types.js').User
+  }
+  createAuthUrl(providerId: string, request?: Request): Promise<URL>
+  handleCallback(providerId: string, request: Request): Promise<import('./auth.js').AuthResponse>
+  getSession(request: Request): Promise<import('./types.js').SessionWithUser | null>
+  signOut(request: Request): Promise<string>
+}

package/src/cookies.ts

@@ -0,0 +1,123 @@
+import { constantTimeEqual } from './crypto.js'
+
+export interface CookieOptions {
+  maxAge?: number
+  expires?: Date
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'lax' | 'strict' | 'none'
+}
+
+/**
+ * Serialize a cookie name-value pair into a Set-Cookie header string.
+ */
+export function serializeCookie(name: string, value: string, options?: CookieOptions): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+
+  if (options?.maxAge !== undefined) {
+    cookie += `; Max-Age=${String(options.maxAge)}`
+  }
+  if (options?.expires) {
+    cookie += `; Expires=${options.expires.toUTCString()}`
+  }
+  if (options?.path) {
+    cookie += `; Path=${options.path}`
+  }
+  if (options?.domain) {
+    cookie += `; Domain=${options.domain}`
+  }
+  if (options?.secure) {
+    cookie += `; Secure`
+  }
+  if (options?.httpOnly) {
+    cookie += `; HttpOnly`
+  }
+  if (options?.sameSite) {
+    cookie += `; SameSite=${options.sameSite}`
+  }
+
+  return cookie
+}
+
+/**
+ * Parse a Cookie header string into a key-value record.
+ * Ignores known cookie attribute names (Path, Domain, Secure, etc.).
+ */
+export function parseCookie(header: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  const knownAttributes = new Set([
+    'path',
+    'domain',
+    'secure',
+    'httponly',
+    'samesite',
+    'max-age',
+    'expires',
+  ])
+
+  for (const pair of header.split(';')) {
+    const separatorIndex = pair.indexOf('=')
+    if (separatorIndex === -1) continue
+
+    const rawName = pair.slice(0, separatorIndex).trim()
+    const rawValue = pair.slice(separatorIndex + 1).trim()
+    if (!rawName) continue
+
+    const name = decodeURIComponent(rawName)
+    // Skip known cookie attribute names
+    if (knownAttributes.has(name.toLowerCase())) continue
+
+    result[name] = decodeURIComponent(rawValue)
+  }
+
+  return result
+}
+
+// Cache HMAC keys per secret to avoid re-importing on every sign/verify
+const hmacKeyCache = new Map<string, Promise<CryptoKey>>()
+
+async function getHmacKey(secret: string): Promise<CryptoKey> {
+  const cached = hmacKeyCache.get(secret)
+  if (cached) return cached
+
+  const keyPromise = crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify'],
+  )
+  hmacKeyCache.set(secret, keyPromise)
+  return keyPromise
+}
+
+/**
+ * Sign a cookie value using HMAC-SHA256.
+ * Returns a string in the format: `value.base64url-signature`.
+ */
+export async function signCookie(value: string, secret: string): Promise<string> {
+  const key = await getHmacKey(secret)
+  const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(value))
+  const encoded = btoa(String.fromCharCode(...new Uint8Array(signature)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+  return `${value}.${encoded}`
+}
+
+/**
+ * Verify a signed cookie value.
+ * Returns the original value if the signature is valid, or null if tampered.
+ */
+export async function verifyCookie(signed: string, secret: string): Promise<string | null> {
+  const lastDot = signed.lastIndexOf('.')
+  if (lastDot === -1) return null
+
+  const value = signed.slice(0, lastDot)
+  if (!value) return null
+
+  const expected = await signCookie(value, secret)
+  return constantTimeEqual(signed, expected) ? value : null
+}

package/src/crypto.ts

@@ -0,0 +1,62 @@
+function base64url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Generate a cryptographically secure random session token (256-bit).
+ * Returns a base64url-encoded string.
+ */
+export function generateSessionToken(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return base64url(bytes)
+}
+
+/**
+ * Hash a session token using SHA-256.
+ * Returns a hex-encoded string for database storage.
+ */
+export async function hashToken(token: string): Promise<string> {
+  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token))
+  return hex(new Uint8Array(hash))
+}
+
+/**
+ * Generate a PKCE code verifier (64 random bytes, base64url encoded).
+ */
+export function generateCodeVerifier(): string {
+  const bytes = new Uint8Array(64)
+  crypto.getRandomValues(bytes)
+  return base64url(bytes)
+}
+
+/**
+ * Generate an S256 PKCE code challenge from a code verifier.
+ */
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  return base64url(new Uint8Array(hash))
+}
+
+/**
+ * Compare two strings in constant time to prevent timing attacks.
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false
+  }
+  let result = 0
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return result === 0
+}