@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.14

package/src/provider/built-in/sqlite-user-store.ts

@@ -0,0 +1,335 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import {
+	type SqliteRevocationDatabase,
+	SqliteTokenRevocationStore,
+} from '../../tokens/sqlite-token-revocation-store'
+import type { TokenRevocationStore } from '../../tokens/token-manager'
+import type { AuthDevice, AuthUser, StoredUser, UserStore } from './user-store'
+import { DeviceOwnershipError, DuplicateEmailError } from './user-store'
+
+/**
+ * Row shape returned by better-sqlite3 for the auth_users table.
+ */
+interface UserRow {
+	id: string
+	email: string
+	name: string
+	email_verified: number
+	created_at: number
+	password_hash: string
+	salt: string
+}
+
+/**
+ * Row shape returned by better-sqlite3 for the auth_devices table.
+ */
+interface DeviceRow {
+	id: string
+	user_id: string
+	public_key: string
+	name: string
+	revoked: number
+	created_at: number
+	last_seen_at: number
+}
+
+/**
+ * Minimal better-sqlite3 subset to avoid a hard dependency on the package.
+ * The real Database instance satisfies this at runtime.
+ */
+interface SqliteDatabase {
+	pragma(source: string): unknown
+	exec(source: string): void
+	prepare(source: string): {
+		run(...params: unknown[]): unknown
+		get(...params: unknown[]): unknown
+		all(...params: unknown[]): unknown[]
+	}
+	transaction<T>(fn: () => T): () => T
+}
+
+/**
+ * SQLite-backed user and device store using better-sqlite3.
+ *
+ * Provides persistent user storage suitable for single-server deployments,
+ * Electron apps, and development environments. Uses WAL mode for concurrent
+ * read/write performance.
+ *
+ * This implementation uses dynamic imports for better-sqlite3 so projects
+ * that do not use SQLite server-side do not need to install it.
+ *
+ * @example
+ * ```typescript
+ * import { createSqliteUserStore } from '@korajs/auth/server'
+ *
+ * const userStore = await createSqliteUserStore({ filename: './auth.db' })
+ * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+ * ```
+ */
+export class SqliteUserStore implements UserStore {
+	private readonly db: SqliteDatabase
+	private revocationStore: SqliteTokenRevocationStore | null = null
+
+	constructor(db: SqliteDatabase) {
+		this.db = db
+		this.db.pragma('journal_mode = WAL')
+		this.ensureTables()
+	}
+
+	/** Token revocations stored in the same SQLite database as the users. */
+	getTokenRevocationStore(): TokenRevocationStore {
+		if (!this.revocationStore) {
+			this.revocationStore = new SqliteTokenRevocationStore(
+				this.db as unknown as SqliteRevocationDatabase,
+			)
+		}
+		return this.revocationStore
+	}
+
+	private ensureTables(): void {
+		this.db.exec(`
+			CREATE TABLE IF NOT EXISTS auth_users (
+				id TEXT PRIMARY KEY,
+				email TEXT NOT NULL UNIQUE COLLATE NOCASE,
+				name TEXT NOT NULL,
+				email_verified INTEGER NOT NULL DEFAULT 0,
+				created_at INTEGER NOT NULL,
+				password_hash TEXT NOT NULL,
+				salt TEXT NOT NULL
+			);
+
+			CREATE TABLE IF NOT EXISTS auth_devices (
+				id TEXT PRIMARY KEY,
+				user_id TEXT NOT NULL,
+				public_key TEXT NOT NULL,
+				name TEXT NOT NULL,
+				revoked INTEGER NOT NULL DEFAULT 0,
+				created_at INTEGER NOT NULL,
+				last_seen_at INTEGER NOT NULL,
+				FOREIGN KEY (user_id) REFERENCES auth_users(id) ON DELETE CASCADE
+			);
+
+			CREATE INDEX IF NOT EXISTS idx_auth_devices_user_id ON auth_devices(user_id);
+		`)
+	}
+
+	async createUser(params: {
+		email: string
+		passwordHash: string
+		salt: string
+		name: string
+	}): Promise<AuthUser> {
+		const normalizedEmail = params.email.toLowerCase()
+		const now = Date.now()
+		const id = randomUUID()
+
+		try {
+			this.db
+				.prepare(`
+				INSERT INTO auth_users (id, email, name, email_verified, created_at, password_hash, salt)
+				VALUES (?, ?, ?, 0, ?, ?, ?)
+			`)
+				.run(id, normalizedEmail, params.name, now, params.passwordHash, params.salt)
+		} catch (err: unknown) {
+			if (err instanceof Error && err.message.includes('UNIQUE constraint failed')) {
+				throw new DuplicateEmailError()
+			}
+			throw err
+		}
+
+		return { id, email: normalizedEmail, name: params.name, emailVerified: false, createdAt: now }
+	}
+
+	async findByEmail(email: string): Promise<StoredUser | null> {
+		const row = this.db
+			.prepare('SELECT * FROM auth_users WHERE email = ?')
+			.get(email.toLowerCase()) as UserRow | undefined
+
+		return row ? rowToStoredUser(row) : null
+	}
+
+	async findById(id: string): Promise<StoredUser | null> {
+		const row = this.db.prepare('SELECT * FROM auth_users WHERE id = ?').get(id) as
+			| UserRow
+			| undefined
+
+		return row ? rowToStoredUser(row) : null
+	}
+
+	async registerDevice(params: {
+		id: string
+		userId: string
+		publicKey: string
+		name: string
+	}): Promise<AuthDevice> {
+		const now = Date.now()
+		// INSERT-or-ignore first, then read: the owner check sees whichever
+		// registration won, even when two users race for the same id.
+		this.db
+			.prepare(`
+			INSERT INTO auth_devices (id, user_id, public_key, name, revoked, created_at, last_seen_at)
+			VALUES (?, ?, ?, ?, 0, ?, ?)
+			ON CONFLICT(id) DO NOTHING
+		`)
+			.run(params.id, params.userId, params.publicKey, params.name, now, now)
+		const existing = this.db.prepare('SELECT * FROM auth_devices WHERE id = ?').get(params.id) as
+			| DeviceRow
+			| undefined
+
+		if (existing && existing.user_id !== params.userId) {
+			throw new DeviceOwnershipError(params.id)
+		}
+		if (existing && !existing.revoked) {
+			return rowToDevice(existing)
+		}
+
+		if (existing) {
+			// Re-activate the owner's previously revoked device
+			this.db
+				.prepare(`
+				UPDATE auth_devices SET revoked = 0, public_key = ?, name = ?, last_seen_at = ?
+				WHERE id = ? AND user_id = ?
+			`)
+				.run(params.publicKey, params.name, now, params.id, params.userId)
+		}
+
+		return {
+			id: params.id,
+			userId: params.userId,
+			publicKey: params.publicKey,
+			name: params.name,
+			revoked: false,
+			createdAt: existing ? existing.created_at : now,
+			lastSeenAt: now,
+		}
+	}
+
+	async findDevice(deviceId: string): Promise<AuthDevice | null> {
+		const row = this.db.prepare('SELECT * FROM auth_devices WHERE id = ?').get(deviceId) as
+			| DeviceRow
+			| undefined
+
+		return row ? rowToDevice(row) : null
+	}
+
+	async listDevices(userId: string): Promise<AuthDevice[]> {
+		const rows = this.db
+			.prepare('SELECT * FROM auth_devices WHERE user_id = ?')
+			.all(userId) as DeviceRow[]
+
+		return rows.map(rowToDevice)
+	}
+
+	async revokeDevice(deviceId: string): Promise<void> {
+		this.db.prepare('UPDATE auth_devices SET revoked = 1 WHERE id = ?').run(deviceId)
+	}
+
+	async setEmailVerified(userId: string, verified: boolean): Promise<void> {
+		this.db
+			.prepare('UPDATE auth_users SET email_verified = ? WHERE id = ?')
+			.run(verified ? 1 : 0, userId)
+	}
+
+	async updatePassword(userId: string, passwordHash: string, salt: string): Promise<void> {
+		this.db
+			.prepare('UPDATE auth_users SET password_hash = ?, salt = ? WHERE id = ?')
+			.run(passwordHash, salt, userId)
+	}
+
+	async listAll(): Promise<StoredUser[]> {
+		const rows = this.db.prepare('SELECT * FROM auth_users').all() as UserRow[]
+		return rows.map(rowToStoredUser)
+	}
+
+	async update(user: StoredUser): Promise<void> {
+		this.db
+			.prepare(`
+			UPDATE auth_users
+			SET email = ?, name = ?, email_verified = ?, password_hash = ?, salt = ?
+			WHERE id = ?
+		`)
+			.run(user.email, user.name, user.emailVerified ? 1 : 0, user.passwordHash, user.salt, user.id)
+	}
+
+	async delete(userId: string): Promise<void> {
+		const deleteInTransaction = this.db.transaction(() => {
+			this.db.prepare('DELETE FROM auth_devices WHERE user_id = ?').run(userId)
+			this.db.prepare('DELETE FROM auth_users WHERE id = ?').run(userId)
+		})
+		deleteInTransaction()
+	}
+
+	async touchDevice(deviceId: string): Promise<void> {
+		this.db
+			.prepare('UPDATE auth_devices SET last_seen_at = ? WHERE id = ?')
+			.run(Date.now(), deviceId)
+	}
+}
+
+/**
+ * Creates a SqliteUserStore from a file path.
+ *
+ * Uses runtime dynamic imports so projects that do not use SQLite server-side
+ * do not need to install `better-sqlite3`.
+ *
+ * @param options.filename - Path to the SQLite database file, or `:memory:` for in-memory
+ */
+export async function createSqliteUserStore(options: {
+	filename: string
+}): Promise<SqliteUserStore> {
+	const Database = await loadBetterSqlite3()
+	ensureDatabaseDirectory(options.filename)
+	const db = new Database(options.filename)
+	return new SqliteUserStore(db as unknown as SqliteDatabase)
+}
+
+async function loadBetterSqlite3(): Promise<new (filename: string) => unknown> {
+	try {
+		// Use createRequire for CJS compatibility with better-sqlite3
+		const { createRequire } = await import('node:module')
+		const require = createRequire(import.meta.url)
+		return require('better-sqlite3') as new (
+			filename: string,
+		) => unknown
+	} catch {
+		throw new Error(
+			'SQLite backend requires the "better-sqlite3" package. Install it in your project dependencies.',
+		)
+	}
+}
+
+function rowToStoredUser(row: UserRow): StoredUser {
+	return {
+		id: row.id,
+		email: row.email,
+		name: row.name,
+		emailVerified: Boolean(row.email_verified),
+		createdAt: row.created_at,
+		passwordHash: row.password_hash,
+		salt: row.salt,
+	}
+}
+
+function rowToDevice(row: DeviceRow): AuthDevice {
+	return {
+		id: row.id,
+		userId: row.user_id,
+		publicKey: row.public_key,
+		name: row.name,
+		revoked: Boolean(row.revoked),
+		createdAt: row.created_at,
+		lastSeenAt: row.last_seen_at,
+	}
+}
+
+/**
+ * Create the directory a SQLite database file lives in, so a default such as
+ * `./.kora/kora-server.db` works on a fresh checkout. In-memory databases and `file:`
+ * URIs are left alone.
+ */
+function ensureDatabaseDirectory(filename: string): void {
+	if (filename === '' || filename === ':memory:' || filename.startsWith('file:')) return
+	mkdirSync(dirname(filename), { recursive: true })
+}

package/src/provider/built-in/sync-scopes.ts

@@ -0,0 +1,85 @@
+import { type ScopeMap, claimScopes } from '@korajs/core'
+
+type MaybePromise<T> = T | Promise<T>
+
+/**
+ * Verified identity of a sync session, derived on the server from a validated
+ * access token. Never contains client-supplied values.
+ */
+export interface VerifiedSyncClaims {
+	/** Verified user id (`sub`). */
+	userId: string
+	/** Verified device id (`dev`). */
+	deviceId: string
+	/** The user's email from the user store. */
+	email: string
+	/** The user's display name from the user store. */
+	name: string
+}
+
+/**
+ * Server-side scope derivation for the sync auth provider (AUTH-1).
+ *
+ * The result is the session's complete grant: the client handshake can only
+ * narrow it, and a schema-scoped collection whose binding is unresolved is
+ * denied (`SCOPE_REQUIRED`), never widened.
+ */
+export interface SyncScopeOptions {
+	/**
+	 * Extra verified scope values merged over the default `{ userId }`, for
+	 * example `{ orgId: await orgOf(userId) }`. Every schema-scoped collection is
+	 * bound from these values. Return `undefined`/`null` for a key to deny the
+	 * collections that need it.
+	 */
+	scopeValues?: (claims: VerifiedSyncClaims) => MaybePromise<Record<string, unknown>>
+	/**
+	 * Full explicit grant. When provided it replaces the default derivation:
+	 * collections it omits are not visible. Use `claimScopes(values, explicit)`
+	 * from `@korajs/core` to combine claim binding with explicit predicates.
+	 */
+	resolveScopes?: (claims: VerifiedSyncClaims) => MaybePromise<ScopeMap>
+}
+
+/** Auth context returned to `@korajs/server` by the sync auth provider. */
+export interface SyncAuthContext {
+	userId: string
+	scopes?: Record<string, Record<string, unknown>>
+	metadata?: Record<string, unknown>
+	/** Access-token expiry (ms since epoch); a session must not outlive it (AUTH-11). */
+	expiresAt?: number
+}
+
+/** Structural `AuthProvider` returned by `toSyncAuthProvider()`. */
+export interface SyncAuthProvider {
+	authenticate(token: string): Promise<SyncAuthContext | null>
+	/**
+	 * Revocation feed (device revoke, sign-out, password reset or change, admin
+	 * revoke). `KoraSyncServer` subscribes automatically and terminates the
+	 * matching live sessions (AUTH-11).
+	 *
+	 * @returns An unsubscribe function
+	 */
+	onRevoke?(
+		listener: (event: { userId: string; deviceId?: string }) => void | Promise<void>,
+	): () => void
+}
+
+/**
+ * Compute the server grant for a verified session.
+ *
+ * @param claims - Verified identity
+ * @param options - Scope derivation options
+ * @returns The scope grant (possibly carrying `$claims` for schema binding)
+ */
+export async function resolveSyncGrant(
+	claims: VerifiedSyncClaims,
+	options: SyncScopeOptions,
+): Promise<ScopeMap> {
+	if (options.resolveScopes) {
+		return options.resolveScopes(claims)
+	}
+	const extra = options.scopeValues ? await options.scopeValues(claims) : {}
+	// The verified subject always wins over anything a resolver returns for
+	// `userId`, so a buggy resolver cannot rebind a session to another user.
+	return claimScopes({ ...extra, userId: claims.userId })
+}