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

package/src/provider/oauth/sqlite-oauth-store.ts

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { DuplicateLinkedIdentityError, type LinkedIdentityStore } from './linked-identity-store'
+import type { LinkedIdentity, OAuthState, OAuthStateStore } from './oauth-types'
+
+interface SqliteDatabase {
+	pragma(source: string): unknown
+	exec(source: string): void
+	prepare(source: string): {
+		run(...params: unknown[]): { changes?: number } | unknown
+		get(...params: unknown[]): unknown
+		all(...params: unknown[]): unknown[]
+	}
+	transaction<T>(fn: () => T): () => T
+}
+
+interface OAuthStateRow {
+	state: string
+	provider: string
+	redirect_uri: string
+	created_at: number
+	expires_at: number
+	metadata_json: string | null
+	code_verifier: string | null
+}
+
+interface LinkedIdentityRow {
+	id: string
+	user_id: string
+	provider: string
+	provider_user_id: string
+	email: string | null
+	linked_at: number
+}
+
+export class SqliteOAuthStateStore implements OAuthStateStore {
+	private readonly db: SqliteDatabase
+
+	constructor(db: SqliteDatabase) {
+		this.db = db
+		this.db.pragma('journal_mode = WAL')
+		this.ensureTables()
+	}
+
+	async store(state: OAuthState): Promise<void> {
+		this.db
+			.prepare(`
+				INSERT OR REPLACE INTO auth_oauth_states
+					(state, provider, redirect_uri, created_at, expires_at, metadata_json, code_verifier)
+				VALUES (?, ?, ?, ?, ?, ?, ?)
+			`)
+			.run(
+				state.state,
+				state.provider,
+				state.redirectUri,
+				state.createdAt,
+				state.expiresAt,
+				state.metadata ? JSON.stringify(state.metadata) : null,
+				state.codeVerifier ?? null,
+			)
+	}
+
+	async consume(stateValue: string): Promise<OAuthState | null> {
+		const consumeInTransaction = this.db.transaction(() => {
+			const row = this.db
+				.prepare('SELECT * FROM auth_oauth_states WHERE state = ?')
+				.get(stateValue) as OAuthStateRow | undefined
+
+			if (!row) return null
+
+			this.db.prepare('DELETE FROM auth_oauth_states WHERE state = ?').run(stateValue)
+			if (Date.now() > row.expires_at) return null
+
+			return rowToOAuthState(row)
+		})
+
+		return consumeInTransaction()
+	}
+
+	async cleanExpired(): Promise<number> {
+		const result = this.db
+			.prepare('DELETE FROM auth_oauth_states WHERE expires_at < ?')
+			.run(Date.now()) as { changes?: number }
+		return result.changes ?? 0
+	}
+
+	private ensureTables(): void {
+		this.db.exec(`
+			CREATE TABLE IF NOT EXISTS auth_oauth_states (
+				state TEXT PRIMARY KEY,
+				provider TEXT NOT NULL,
+				redirect_uri TEXT NOT NULL,
+				created_at INTEGER NOT NULL,
+				expires_at INTEGER NOT NULL,
+				metadata_json TEXT,
+				code_verifier TEXT
+			);
+
+			CREATE INDEX IF NOT EXISTS idx_auth_oauth_states_expires_at
+				ON auth_oauth_states(expires_at);
+		`)
+	}
+}
+
+export class SqliteLinkedIdentityStore implements LinkedIdentityStore {
+	private readonly db: SqliteDatabase
+
+	constructor(db: SqliteDatabase) {
+		this.db = db
+		this.db.pragma('journal_mode = WAL')
+		this.ensureTables()
+	}
+
+	async findByProvider(provider: string, providerUserId: string): Promise<LinkedIdentity | null> {
+		const row = this.db
+			.prepare(`
+				SELECT * FROM auth_linked_identities
+				WHERE provider = ? AND provider_user_id = ?
+			`)
+			.get(provider, providerUserId) as LinkedIdentityRow | undefined
+
+		return row ? rowToLinkedIdentity(row) : null
+	}
+
+	async findByUser(userId: string): Promise<LinkedIdentity[]> {
+		const rows = this.db
+			.prepare(`
+				SELECT * FROM auth_linked_identities
+				WHERE user_id = ?
+				ORDER BY linked_at ASC
+			`)
+			.all(userId) as LinkedIdentityRow[]
+
+		return rows.map(rowToLinkedIdentity)
+	}
+
+	async create(params: {
+		userId: string
+		provider: string
+		providerUserId: string
+		email: string | null
+	}): Promise<LinkedIdentity> {
+		const identity: LinkedIdentity = {
+			id: randomUUID(),
+			userId: params.userId,
+			provider: params.provider,
+			providerUserId: params.providerUserId,
+			email: params.email,
+			linkedAt: Date.now(),
+		}
+
+		try {
+			this.db
+				.prepare(`
+					INSERT INTO auth_linked_identities
+						(id, user_id, provider, provider_user_id, email, linked_at)
+					VALUES (?, ?, ?, ?, ?, ?)
+				`)
+				.run(
+					identity.id,
+					identity.userId,
+					identity.provider,
+					identity.providerUserId,
+					identity.email,
+					identity.linkedAt,
+				)
+		} catch (error) {
+			if (error instanceof Error && error.message.includes('UNIQUE constraint failed')) {
+				throw new DuplicateLinkedIdentityError(params.provider)
+			}
+			throw error
+		}
+
+		return identity
+	}
+
+	async delete(userId: string, provider: string): Promise<void> {
+		this.db
+			.prepare('DELETE FROM auth_linked_identities WHERE user_id = ? AND provider = ?')
+			.run(userId, provider)
+	}
+
+	private ensureTables(): void {
+		this.db.exec(`
+			CREATE TABLE IF NOT EXISTS auth_linked_identities (
+				id TEXT PRIMARY KEY,
+				user_id TEXT NOT NULL,
+				provider TEXT NOT NULL,
+				provider_user_id TEXT NOT NULL,
+				email TEXT,
+				linked_at INTEGER NOT NULL,
+				UNIQUE(provider, provider_user_id),
+				UNIQUE(user_id, provider)
+			);
+
+			CREATE INDEX IF NOT EXISTS idx_auth_linked_identities_user_id
+				ON auth_linked_identities(user_id);
+		`)
+	}
+}
+
+export async function createSqliteOAuthStateStore(options: {
+	filename: string
+}): Promise<SqliteOAuthStateStore> {
+	const Database = await loadBetterSqlite3()
+	const db = new Database(options.filename)
+	return new SqliteOAuthStateStore(db as unknown as SqliteDatabase)
+}
+
+export async function createSqliteLinkedIdentityStore(options: {
+	filename: string
+}): Promise<SqliteLinkedIdentityStore> {
+	const Database = await loadBetterSqlite3()
+	const db = new Database(options.filename)
+	return new SqliteLinkedIdentityStore(db as unknown as SqliteDatabase)
+}
+
+export async function createSqliteOAuthStores(options: { filename: string }): Promise<{
+	stateStore: SqliteOAuthStateStore
+	linkedIdentityStore: SqliteLinkedIdentityStore
+}> {
+	const Database = await loadBetterSqlite3()
+	ensureDatabaseDirectory(options.filename)
+	const db = new Database(options.filename) as unknown as SqliteDatabase
+	return {
+		stateStore: new SqliteOAuthStateStore(db),
+		linkedIdentityStore: new SqliteLinkedIdentityStore(db),
+	}
+}
+
+async function loadBetterSqlite3(): Promise<new (filename: string) => unknown> {
+	try {
+		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 OAuth stores require the "better-sqlite3" package. Install it in your project dependencies.',
+		)
+	}
+}
+
+function rowToOAuthState(row: OAuthStateRow): OAuthState {
+	return {
+		state: row.state,
+		provider: row.provider,
+		redirectUri: row.redirect_uri,
+		createdAt: row.created_at,
+		expiresAt: row.expires_at,
+		metadata: parseMetadata(row.metadata_json),
+		codeVerifier: row.code_verifier ?? undefined,
+	}
+}
+
+function parseMetadata(value: string | null): Record<string, unknown> | undefined {
+	if (!value) return undefined
+	const parsed = JSON.parse(value) as unknown
+	return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+		? (parsed as Record<string, unknown>)
+		: undefined
+}
+
+function rowToLinkedIdentity(row: LinkedIdentityRow): LinkedIdentity {
+	return {
+		id: row.id,
+		userId: row.user_id,
+		provider: row.provider,
+		providerUserId: row.provider_user_id,
+		email: row.email,
+		linkedAt: row.linked_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/rbac/rbac-engine.ts

@@ -0,0 +1,323 @@
+import type { OrgStore } from '../org/org-store'
+import type {
+	CollectionScopeResolver,
+	Permission,
+	RbacConfig,
+	RoleDefinition,
+	ScopeContext,
+	ScopeFilter,
+	SyncScopes,
+} from './rbac-types'
+import {
+	BUILT_IN_ROLES,
+	CircularInheritanceError,
+	RoleNotFoundError,
+	permissionCovers,
+} from './rbac-types'
+
+// ============================================================================
+// RbacEngine
+// ============================================================================
+
+/**
+ * Permission evaluation engine for role-based access control.
+ *
+ * The engine resolves permissions through role inheritance, supports
+ * wildcard matching, and integrates with the OrgStore for membership lookups.
+ *
+ * @example
+ * ```typescript
+ * const rbac = new RbacEngine({ orgStore })
+ *
+ * // Check a permission
+ * const canWrite = await rbac.hasPermission('user-1', 'org-1', 'todos:write')
+ *
+ * // Get all permissions for a user in an org
+ * const perms = await rbac.getUserPermissions('user-1', 'org-1')
+ *
+ * // Resolve sync scopes
+ * const scopes = await rbac.resolveScopes('user-1', 'org-1')
+ * ```
+ */
+export class RbacEngine {
+	private readonly orgStore: OrgStore
+	private readonly roleMap: Map<string, RoleDefinition>
+	private readonly resolvedPermissions = new Map<string, Permission[]>()
+	private readonly collectionResolvers = new Map<string, CollectionScopeResolver>()
+
+	constructor(orgStore: OrgStore, config?: RbacConfig) {
+		this.orgStore = orgStore
+
+		const roles = config?.roles ?? [...BUILT_IN_ROLES]
+		this.roleMap = new Map()
+		for (const role of roles) {
+			this.roleMap.set(role.name, role)
+		}
+
+		// Validate and pre-resolve all role permissions
+		this.validateRoles()
+	}
+
+	// --- Permission Checks ---
+
+	/**
+	 * Check if a user has a specific permission in an organization.
+	 *
+	 * Resolves the user's role from the org membership, then evaluates
+	 * the role's permissions (including inherited ones) against the required permission.
+	 *
+	 * Returns false (not an error) if the user is not a member.
+	 */
+	async hasPermission(userId: string, orgId: string, permission: Permission): Promise<boolean> {
+		const membership = await this.orgStore.getMembership(orgId, userId)
+		if (!membership) return false
+
+		const rolePerms = this.getRolePermissions(membership.role)
+		return rolePerms.some((granted) => permissionCovers(granted, permission))
+	}
+
+	/**
+	 * Get all effective permissions for a user in an organization.
+	 *
+	 * Returns an empty array if the user is not a member.
+	 */
+	async getUserPermissions(userId: string, orgId: string): Promise<Permission[]> {
+		const membership = await this.orgStore.getMembership(orgId, userId)
+		if (!membership) return []
+
+		return this.getRolePermissions(membership.role)
+	}
+
+	/**
+	 * Get all effective permissions for a role name.
+	 * Includes permissions from inherited roles.
+	 *
+	 * @throws {RoleNotFoundError} if the role is not defined
+	 */
+	getRolePermissions(roleName: string): Permission[] {
+		const cached = this.resolvedPermissions.get(roleName)
+		if (cached) return cached
+
+		if (!this.roleMap.has(roleName)) {
+			throw new RoleNotFoundError(roleName)
+		}
+
+		const perms = this.resolvePermissionsForRole(roleName, new Set())
+		this.resolvedPermissions.set(roleName, perms)
+		return perms
+	}
+
+	/**
+	 * Check if a role has a specific permission.
+	 */
+	roleHasPermission(roleName: string, permission: Permission): boolean {
+		const perms = this.getRolePermissions(roleName)
+		return perms.some((granted) => permissionCovers(granted, permission))
+	}
+
+	// --- Scope Resolution ---
+
+	/**
+	 * Register a custom scope resolver for a collection.
+	 *
+	 * Custom resolvers override the default scope logic for that collection.
+	 */
+	registerScopeResolver(collection: string, resolver: CollectionScopeResolver): void {
+		this.collectionResolvers.set(collection, resolver)
+	}
+
+	/**
+	 * Resolve sync scopes for a user in an organization.
+	 *
+	 * The scopes determine what data the user can see and modify during sync.
+	 * - Owner/Admin: all org data
+	 * - Member: all org data (read + write)
+	 * - Viewer: all org data (read-only)
+	 * - Billing: no data scopes (billing-only access)
+	 *
+	 * Custom collection resolvers can override the defaults.
+	 *
+	 * @param collections - List of collection names to resolve scopes for.
+	 *                      If not provided, only custom-registered collections are included.
+	 */
+	async resolveScopes(
+		userId: string,
+		orgId: string,
+		collections?: string[],
+	): Promise<SyncScopes | null> {
+		const membership = await this.orgStore.getMembership(orgId, userId)
+		if (!membership) return null
+
+		const permissions = this.getRolePermissions(membership.role)
+		const ctx: ScopeContext = {
+			userId,
+			orgId,
+			role: membership.role,
+			permissions,
+		}
+
+		const scopes: SyncScopes = {}
+
+		// Check if user has any data permissions at all
+		const hasAnyRead = permissions.some((p) => permissionCovers(p, '*:read' as Permission))
+		if (!hasAnyRead) {
+			// No data access (e.g., billing-only role)
+			return scopes
+		}
+
+		const isReadOnly = !permissions.some((p) => permissionCovers(p, '*:write' as Permission))
+
+		const collectionsToResolve = collections ?? [...this.collectionResolvers.keys()]
+
+		for (const collection of collectionsToResolve) {
+			// Check custom resolver first
+			const customResolver = this.collectionResolvers.get(collection)
+			if (customResolver) {
+				const customScope = customResolver(ctx)
+				if (customScope) {
+					scopes[collection] = customScope
+				}
+				continue
+			}
+
+			// Default scope: filter by orgId
+			const scope: ScopeFilter = { orgId }
+			if (isReadOnly) {
+				scope.__readonly = true
+			}
+			scopes[collection] = scope
+		}
+
+		return scopes
+	}
+
+	// --- Role Management ---
+
+	/**
+	 * Get all defined role names.
+	 */
+	getRoleNames(): string[] {
+		return [...this.roleMap.keys()]
+	}
+
+	/**
+	 * Get a role definition by name.
+	 */
+	getRoleDefinition(roleName: string): RoleDefinition | null {
+		return this.roleMap.get(roleName) ?? null
+	}
+
+	// --- Private ---
+
+	/**
+	 * Validate all role definitions for circular inheritance and unknown references.
+	 */
+	private validateRoles(): void {
+		for (const role of this.roleMap.values()) {
+			if (role.inherits) {
+				for (const parent of role.inherits) {
+					if (!this.roleMap.has(parent)) {
+						throw new RoleNotFoundError(parent)
+					}
+				}
+			}
+		}
+
+		// Check for circular inheritance
+		for (const role of this.roleMap.values()) {
+			this.detectCircularInheritance(role.name, new Set())
+		}
+	}
+
+	/**
+	 * Detect circular inheritance in role hierarchy.
+	 */
+	private detectCircularInheritance(roleName: string, visited: Set<string>): void {
+		if (visited.has(roleName)) {
+			throw new CircularInheritanceError([...visited, roleName])
+		}
+		visited.add(roleName)
+
+		const role = this.roleMap.get(roleName)
+		if (role?.inherits) {
+			for (const parent of role.inherits) {
+				this.detectCircularInheritance(parent, new Set(visited))
+			}
+		}
+	}
+
+	/**
+	 * Recursively resolve all permissions for a role, including inherited permissions.
+	 */
+	private resolvePermissionsForRole(roleName: string, visited: Set<string>): Permission[] {
+		if (visited.has(roleName)) return []
+		visited.add(roleName)
+
+		const role = this.roleMap.get(roleName)
+		if (!role) return []
+
+		const perms = new Set<Permission>(role.permissions)
+
+		if (role.inherits) {
+			for (const parent of role.inherits) {
+				const parentPerms = this.resolvePermissionsForRole(parent, visited)
+				for (const p of parentPerms) {
+					perms.add(p)
+				}
+			}
+		}
+
+		return [...perms]
+	}
+}
+
+// ============================================================================
+// defineRoles builder
+// ============================================================================
+
+/**
+ * Builder for defining custom roles.
+ *
+ * @example
+ * ```typescript
+ * const roles = defineRoles()
+ *   .role('viewer', ['*:read'])
+ *   .role('editor', ['*:write'], { inherits: ['viewer'] })
+ *   .role('admin', ['org:manage-members'], { inherits: ['editor'] })
+ *   .build()
+ * ```
+ */
+export function defineRoles(): RoleBuilder {
+	return new RoleBuilder()
+}
+
+class RoleBuilder {
+	private roles: RoleDefinition[] = []
+
+	/**
+	 * Add a role definition.
+	 */
+	role(name: string, permissions: Permission[], options?: { inherits?: string[] }): RoleBuilder {
+		this.roles.push({
+			name,
+			permissions,
+			inherits: options?.inherits,
+		})
+		return this
+	}
+
+	/**
+	 * Include the built-in roles as a base.
+	 */
+	withBuiltInRoles(): RoleBuilder {
+		this.roles = [...BUILT_IN_ROLES, ...this.roles]
+		return this
+	}
+
+	/**
+	 * Build and return the role definitions array.
+	 */
+	build(): RoleDefinition[] {
+		return [...this.roles]
+	}
+}