@korajs/auth 1.0.0-beta.11 → 1.0.0-beta.13

package/src/postgres/ensure-schema.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal postgres-js tagged-template client used for schema setup. `begin` is
+ * optional so the narrowest store clients (a bare tagged template) still work.
+ */
+export interface PostgresDdlClient {
+	(template: TemplateStringsArray, ...args: unknown[]): Promise<Record<string, unknown>[]>
+	begin?: <T>(fn: (sql: PostgresDdlClient) => Promise<T>) => Promise<T>
+}
+
+/**
+ * Advisory-lock key serializing every Kora auth schema setup on one database
+ * ("Kora" in ASCII).
+ */
+export const AUTH_SCHEMA_LOCK_KEY = 0x4b6f7261
+
+/**
+ * SQLSTATEs a concurrent `CREATE ... IF NOT EXISTS` can still raise when two
+ * sessions create the same object at once: the check and the catalog insert are not
+ * atomic, so the loser fails on the catalog's unique index ("type ... already
+ * exists", 23505) or as a duplicate table / object (42P07 / 42710).
+ */
+const CONCURRENT_DDL_CODES = new Set(['23505', '42P07', '42710'])
+
+const MAX_ATTEMPTS = 3
+
+/**
+ * Create a store's tables safely when several server instances start against an
+ * empty database at the same time.
+ *
+ * With a transaction-capable client the DDL runs inside one transaction holding
+ * {@link AUTH_SCHEMA_LOCK_KEY} as a transaction-scoped advisory lock, so concurrent
+ * first starts are serialized and the later ones find every object already there.
+ * A client without `begin` (or a database that still reports a creation race) is
+ * retried: the statements are idempotent (`IF NOT EXISTS`), so a retry after a lost
+ * race succeeds.
+ *
+ * @param sql - The postgres-js client
+ * @param ddl - Idempotent DDL statements, run with the client (or transaction) given
+ */
+export async function ensurePostgresSchema(
+	sql: PostgresDdlClient,
+	ddl: (client: PostgresDdlClient) => Promise<void>,
+): Promise<void> {
+	for (let attempt = 1; ; attempt++) {
+		try {
+			if (typeof sql.begin === 'function') {
+				await sql.begin(async (tx) => {
+					await tx`SELECT pg_advisory_xact_lock(${AUTH_SCHEMA_LOCK_KEY}::bigint)`
+					await ddl(tx)
+				})
+			} else {
+				await ddl(sql)
+			}
+			return
+		} catch (error) {
+			if (attempt >= MAX_ATTEMPTS || !isConcurrentDdlError(error)) throw error
+		}
+	}
+}
+
+function isConcurrentDdlError(error: unknown): boolean {
+	if (error === null || typeof error !== 'object') return false
+	const code = (error as { code?: unknown }).code
+	return typeof code === 'string' && CONCURRENT_DDL_CODES.has(code)
+}

package/src/provider/adapter.ts

@@ -0,0 +1,246 @@
+import type { TokenManager } from '../tokens/token-manager'
+import type { AuthTokens } from '../types'
+import { type AuthRoutesConfig, BuiltInAuthRoutes } from './built-in/auth-routes'
+import type { AuthDevice, AuthUser, UserStore } from './built-in/user-store'
+
+/**
+ * Parameters for signing up a new user.
+ */
+export interface SignUpParams {
+	/** The user's email address */
+	email: string
+	/** The plaintext password */
+	password: string
+	/** Optional display name */
+	name?: string
+	/** Optional device ID to register with the account */
+	deviceId?: string
+	/** Optional device public key (base64url) */
+	devicePublicKey?: string
+}
+
+/**
+ * Parameters for signing in an existing user.
+ */
+export interface SignInParams {
+	/** The user's email address */
+	email: string
+	/** The plaintext password */
+	password: string
+	/** Optional device ID to register or associate */
+	deviceId?: string
+	/** Optional device public key (base64url) */
+	devicePublicKey?: string
+}
+
+/**
+ * Abstraction for authentication providers.
+ *
+ * This interface allows swapping between the built-in email/password provider
+ * and external providers (OAuth, SAML, custom) without changing application code.
+ * Every provider must support the same core operations: sign up, sign in,
+ * token refresh, token validation, user lookup, and device management.
+ *
+ * @example
+ * ```typescript
+ * // Use the built-in provider
+ * const provider: AuthProviderAdapter = new BuiltInProvider({
+ *   userStore: new InMemoryUserStore(),
+ *   tokenManager: new TokenManager({ secret: 'my-secret' }),
+ * })
+ *
+ * const { user, tokens } = await provider.signUp({
+ *   email: 'alice@example.com',
+ *   password: 'secure-password-123',
+ * })
+ * ```
+ */
+export interface AuthProviderAdapter {
+	/**
+	 * Create a new user account and issue authentication tokens.
+	 *
+	 * @param params - Sign-up parameters including email, password, and optional device info
+	 * @returns The created user and tokens
+	 * @throws If the email is already registered or input validation fails
+	 */
+	signUp(params: SignUpParams): Promise<{ user: AuthUser; tokens: AuthTokens }>
+
+	/**
+	 * Authenticate an existing user and issue tokens.
+	 *
+	 * @param params - Sign-in parameters including email and password
+	 * @returns The authenticated user and tokens
+	 * @throws If the credentials are invalid
+	 */
+	signIn(params: SignInParams): Promise<{ user: AuthUser; tokens: AuthTokens }>
+
+	/**
+	 * Exchange a refresh token for new tokens (rotation).
+	 *
+	 * @param refreshToken - The current refresh token
+	 * @returns A new token pair
+	 * @throws If the refresh token is invalid or expired
+	 */
+	refreshTokens(refreshToken: string): Promise<AuthTokens>
+
+	/**
+	 * Validate an access token and extract identity claims.
+	 *
+	 * @param token - The JWT access token
+	 * @returns User ID and device ID if valid, or null if invalid/expired
+	 */
+	validateAccessToken(token: string): Promise<{ userId: string; deviceId: string } | null>
+
+	/**
+	 * Look up a user by ID.
+	 *
+	 * @param userId - The user's ID
+	 * @returns The user profile, or null if not found
+	 */
+	getUser(userId: string): Promise<AuthUser | null>
+
+	/**
+	 * Revoke a device. Requires a valid access token for authorization.
+	 *
+	 * @param accessToken - The caller's access token
+	 * @param deviceId - The ID of the device to revoke
+	 * @throws If the token is invalid or the device does not belong to the caller
+	 */
+	revokeDevice(accessToken: string, deviceId: string): Promise<void>
+
+	/**
+	 * List all devices for the authenticated user.
+	 *
+	 * @param accessToken - The caller's access token
+	 * @returns Array of device records
+	 * @throws If the token is invalid
+	 */
+	listDevices(accessToken: string): Promise<AuthDevice[]>
+}
+
+/**
+ * Error thrown by provider adapter methods when an operation fails.
+ * Wraps the HTTP-style status and error message from route handlers
+ * into an exception for use in the adapter pattern.
+ */
+export class AuthProviderError extends Error {
+	/** HTTP-style status code */
+	readonly status: number
+
+	constructor(message: string, status: number) {
+		super(message)
+		this.name = 'AuthProviderError'
+		this.status = status
+	}
+}
+
+/**
+ * Built-in authentication provider implementing email/password authentication.
+ *
+ * Wraps {@link BuiltInAuthRoutes} in the {@link AuthProviderAdapter} interface,
+ * converting HTTP-style responses into direct return values and exceptions.
+ * This is the default provider shipped with Kora and is suitable for
+ * applications that want simple email/password auth without external services.
+ *
+ * @example
+ * ```typescript
+ * import { BuiltInProvider } from '@korajs/auth'
+ * import { InMemoryUserStore } from '@korajs/auth'
+ * import { TokenManager } from '@korajs/auth'
+ *
+ * const provider = new BuiltInProvider({
+ *   userStore: new InMemoryUserStore(),
+ *   tokenManager: new TokenManager({ secret: process.env.AUTH_SECRET }),
+ * })
+ *
+ * const { user, tokens } = await provider.signUp({
+ *   email: 'alice@example.com',
+ *   password: 'strong-password-123',
+ *   name: 'Alice',
+ * })
+ * ```
+ */
+export class BuiltInProvider implements AuthProviderAdapter {
+	private readonly routes: BuiltInAuthRoutes
+	private readonly tokenManager: TokenManager
+	private readonly userStore: UserStore
+
+	constructor(config: AuthRoutesConfig) {
+		this.routes = new BuiltInAuthRoutes(config)
+		this.tokenManager = config.tokenManager
+		this.userStore = config.userStore
+	}
+
+	/** @inheritdoc */
+	async signUp(params: SignUpParams): Promise<{ user: AuthUser; tokens: AuthTokens }> {
+		const result = await this.routes.handleSignUp(params)
+		if ('error' in result.body) {
+			throw new AuthProviderError(result.body.error, result.status)
+		}
+		return result.body.data
+	}
+
+	/** @inheritdoc */
+	async signIn(params: SignInParams): Promise<{ user: AuthUser; tokens: AuthTokens }> {
+		const result = await this.routes.handleSignIn(params)
+		if ('error' in result.body) {
+			throw new AuthProviderError(result.body.error, result.status)
+		}
+		if ('mfaRequired' in result.body.data) {
+			// This adapter has no second-factor step; MFA users must sign in through
+			// the HTTP routes (POST /auth/mfa/verify).
+			throw new AuthProviderError('A second factor is required for this account.', 401)
+		}
+		return result.body.data
+	}
+
+	/** @inheritdoc */
+	async refreshTokens(refreshToken: string): Promise<AuthTokens> {
+		const result = await this.routes.handleRefresh({ refreshToken })
+		if ('error' in result.body) {
+			throw new AuthProviderError(result.body.error, result.status)
+		}
+		return result.body.data
+	}
+
+	/** @inheritdoc */
+	async validateAccessToken(token: string): Promise<{ userId: string; deviceId: string } | null> {
+		const payload = this.tokenManager.validateToken(token)
+		if (payload === null || payload.type !== 'access') {
+			return null
+		}
+		return { userId: payload.sub, deviceId: payload.dev }
+	}
+
+	/** @inheritdoc */
+	async getUser(userId: string): Promise<AuthUser | null> {
+		const stored = await this.userStore.findById(userId)
+		if (stored === null) {
+			return null
+		}
+		return {
+			id: stored.id,
+			email: stored.email,
+			name: stored.name,
+			emailVerified: stored.emailVerified,
+			createdAt: stored.createdAt,
+		}
+	}
+
+	/** @inheritdoc */
+	async revokeDevice(accessToken: string, deviceId: string): Promise<void> {
+		const result = await this.routes.handleRevokeDevice(accessToken, deviceId)
+		if ('error' in result.body) {
+			throw new AuthProviderError(result.body.error, result.status)
+		}
+	}
+
+	/** @inheritdoc */
+	async listDevices(accessToken: string): Promise<AuthDevice[]> {
+		const result = await this.routes.handleListDevices(accessToken)
+		if ('error' in result.body) {
+			throw new AuthProviderError(result.body.error, result.status)
+		}
+		return result.body.data
+	}
+}