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

package/src/rbac/rbac-types.ts

@@ -0,0 +1,210 @@
+import { KoraError } from '@korajs/core'
+
+// ============================================================================
+// Permissions
+// ============================================================================
+
+/**
+ * A permission is a `resource:action` string.
+ *
+ * Resources are typically collection names or system resources.
+ * Actions are the operations allowed on that resource.
+ *
+ * @example
+ * ```typescript
+ * const permission: Permission = 'todos:write'
+ * const adminPerm: Permission = 'org:manage-members'
+ * const wildcard: Permission = 'todos:*'  // all actions on todos
+ * const superAdmin: Permission = '*:*'     // all actions on all resources
+ * ```
+ */
+export type Permission = `${string}:${string}`
+
+/**
+ * Parse a permission string into its resource and action parts.
+ */
+export function parsePermission(permission: Permission): { resource: string; action: string } {
+	const colonIndex = permission.indexOf(':')
+	if (colonIndex === -1) {
+		throw new InvalidPermissionError(permission)
+	}
+	const resource = permission.slice(0, colonIndex)
+	const action = permission.slice(colonIndex + 1)
+	if (resource.length === 0 || action.length === 0) {
+		throw new InvalidPermissionError(permission)
+	}
+	return { resource, action }
+}
+
+/**
+ * Check if a granted permission covers a required permission.
+ * Supports wildcards: `todos:*` covers `todos:read`, `*:*` covers everything.
+ */
+export function permissionCovers(granted: Permission, required: Permission): boolean {
+	const g = parsePermission(granted)
+	const r = parsePermission(required)
+
+	const resourceMatch = g.resource === '*' || g.resource === r.resource
+	const actionMatch = g.action === '*' || g.action === r.action
+	return resourceMatch && actionMatch
+}
+
+// ============================================================================
+// Role Definitions
+// ============================================================================
+
+/**
+ * A role definition describes a named set of permissions with optional inheritance.
+ *
+ * Roles form a hierarchy via `inherits`. When evaluating permissions,
+ * all inherited roles' permissions are included transitively.
+ *
+ * @example
+ * ```typescript
+ * const roles: RoleDefinition[] = [
+ *   { name: 'viewer', permissions: ['todos:read', 'projects:read'] },
+ *   { name: 'member', permissions: ['todos:write', 'projects:write'], inherits: ['viewer'] },
+ *   { name: 'admin', permissions: ['org:manage-members'], inherits: ['member'] },
+ * ]
+ * ```
+ */
+export interface RoleDefinition {
+	/** Unique name for this role */
+	name: string
+	/** Permissions directly granted to this role */
+	permissions: Permission[]
+	/** Roles this role inherits from (all their permissions are included) */
+	inherits?: string[]
+}
+
+// ============================================================================
+// Built-in Roles
+// ============================================================================
+
+/**
+ * Default built-in roles for organizations.
+ *
+ * These can be overridden or extended using `defineRoles()`.
+ */
+export const BUILT_IN_ROLES: readonly RoleDefinition[] = [
+	{
+		name: 'viewer',
+		permissions: ['*:read'],
+	},
+	{
+		name: 'billing',
+		permissions: ['org:billing'],
+	},
+	{
+		name: 'member',
+		permissions: ['*:write', '*:delete'],
+		inherits: ['viewer'],
+	},
+	{
+		name: 'admin',
+		permissions: ['org:manage-members', 'org:manage-settings', 'org:manage-invitations'],
+		inherits: ['member'],
+	},
+	{
+		name: 'owner',
+		permissions: ['*:*'],
+	},
+] as const
+
+// ============================================================================
+// RBAC Configuration
+// ============================================================================
+
+/**
+ * Configuration for the RBAC engine.
+ */
+export interface RbacConfig {
+	/** Role definitions. Defaults to BUILT_IN_ROLES if not provided. */
+	roles?: RoleDefinition[]
+}
+
+// ============================================================================
+// Scope Types
+// ============================================================================
+
+/**
+ * A sync scope filter for a single collection.
+ * The keys are field names and values are the required values.
+ * A special `__readonly` key can be set to restrict to read-only access.
+ *
+ * @example
+ * ```typescript
+ * // Only sync todos belonging to the user within the org
+ * const scope: ScopeFilter = { orgId: 'org-123', userId: 'user-456' }
+ *
+ * // Read-only scope for viewers
+ * const readOnlyScope: ScopeFilter = { orgId: 'org-123', __readonly: true }
+ * ```
+ */
+export interface ScopeFilter {
+	[field: string]: unknown
+}
+
+/**
+ * A complete set of sync scopes, keyed by collection name.
+ *
+ * @example
+ * ```typescript
+ * const scopes: SyncScopes = {
+ *   todos: { orgId: 'org-123' },
+ *   projects: { orgId: 'org-123' },
+ * }
+ * ```
+ */
+export type SyncScopes = Record<string, ScopeFilter>
+
+/**
+ * Custom scope resolver for a specific collection.
+ * Given the user context, returns the scope filter for that collection.
+ */
+export type CollectionScopeResolver = (ctx: ScopeContext) => ScopeFilter | null
+
+/**
+ * Context passed to scope resolvers.
+ */
+export interface ScopeContext {
+	userId: string
+	orgId: string
+	role: string
+	permissions: Permission[]
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class RbacError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'RbacError'
+	}
+}
+
+export class InvalidPermissionError extends RbacError {
+	constructor(permission: string) {
+		super(
+			`Invalid permission format: "${permission}". Expected "resource:action".`,
+			'INVALID_PERMISSION',
+			{ permission },
+		)
+	}
+}
+
+export class RoleNotFoundError extends RbacError {
+	constructor(role: string) {
+		super(`Role "${role}" is not defined.`, 'ROLE_NOT_FOUND', { role })
+	}
+}
+
+export class CircularInheritanceError extends RbacError {
+	constructor(chain: string[]) {
+		super(`Circular role inheritance detected: ${chain.join(' → ')}.`, 'CIRCULAR_INHERITANCE', {
+			chain,
+		})
+	}
+}

package/src/rbac/scope-resolver.ts

@@ -0,0 +1,140 @@
+import type { OrgStore } from '../org/org-store'
+import type { OrgRole } from '../org/org-types'
+import type { RbacEngine } from './rbac-engine'
+import type {
+	CollectionScopeResolver,
+	Permission,
+	ScopeContext,
+	ScopeFilter,
+	SyncScopes,
+} from './rbac-types'
+import { permissionCovers } from './rbac-types'
+
+// ============================================================================
+// OrgScopeResolver
+// ============================================================================
+
+/**
+ * Resolves sync scopes for org-aware data filtering.
+ *
+ * Given a user, an organization, and a set of collections, this resolver
+ * determines what data the user should receive during sync:
+ *
+ * - **Owner/Admin**: All data in the org (no field-level filtering)
+ * - **Member**: All org data with read/write access
+ * - **Viewer**: All org data with read-only flag
+ * - **Billing**: No data access (empty scopes)
+ *
+ * Developers can register per-collection scope resolvers for fine-grained control.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new OrgScopeResolver(orgStore, rbacEngine)
+ *
+ * // Custom scope: members only see their own todos
+ * resolver.registerCollectionScope('todos', (ctx) => {
+ *   if (ctx.role === 'member') {
+ *     return { orgId: ctx.orgId, userId: ctx.userId }
+ *   }
+ *   return { orgId: ctx.orgId }  // admins/owners see all
+ * })
+ *
+ * const scopes = await resolver.resolve('user-1', 'org-1', ['todos', 'projects'])
+ * // { todos: { orgId: 'org-1', userId: 'user-1' }, projects: { orgId: 'org-1' } }
+ * ```
+ */
+export class OrgScopeResolver {
+	private readonly orgStore: OrgStore
+	private readonly rbac: RbacEngine
+	private readonly collectionScopes = new Map<string, CollectionScopeResolver>()
+
+	constructor(orgStore: OrgStore, rbac: RbacEngine) {
+		this.orgStore = orgStore
+		this.rbac = rbac
+	}
+
+	/**
+	 * Register a custom scope resolver for a collection.
+	 * This overrides the default orgId-based filtering for that collection.
+	 */
+	registerCollectionScope(collection: string, resolver: CollectionScopeResolver): void {
+		this.collectionScopes.set(collection, resolver)
+	}
+
+	/**
+	 * Resolve sync scopes for all specified collections.
+	 *
+	 * Returns null if the user is not a member of the organization.
+	 * Returns an empty object if the user has no data access (e.g., billing role).
+	 */
+	async resolve(userId: string, orgId: string, collections: string[]): Promise<SyncScopes | null> {
+		const membership = await this.orgStore.getMembership(orgId, userId)
+		if (!membership) return null
+
+		const permissions = this.rbac.getRolePermissions(membership.role)
+		const ctx: ScopeContext = {
+			userId,
+			orgId,
+			role: membership.role,
+			permissions,
+		}
+
+		const scopes: SyncScopes = {}
+
+		for (const collection of collections) {
+			const scope = this.resolveCollectionScope(ctx, collection)
+			if (scope) {
+				scopes[collection] = scope
+			}
+		}
+
+		return scopes
+	}
+
+	/**
+	 * Check if a user can write to a specific collection in an org.
+	 */
+	async canWrite(userId: string, orgId: string, collection: string): Promise<boolean> {
+		return this.rbac.hasPermission(userId, orgId, `${collection}:write` as Permission)
+	}
+
+	/**
+	 * Check if a user can read from a specific collection in an org.
+	 */
+	async canRead(userId: string, orgId: string, collection: string): Promise<boolean> {
+		return this.rbac.hasPermission(userId, orgId, `${collection}:read` as Permission)
+	}
+
+	// --- Private ---
+
+	private resolveCollectionScope(ctx: ScopeContext, collection: string): ScopeFilter | null {
+		// Check if user has read permission for this collection
+		const canRead = ctx.permissions.some(
+			(p) =>
+				permissionCovers(p, `${collection}:read` as Permission) ||
+				permissionCovers(p, '*:read' as Permission),
+		)
+		if (!canRead) return null
+
+		// Check custom resolver
+		const customResolver = this.collectionScopes.get(collection)
+		if (customResolver) {
+			return customResolver(ctx)
+		}
+
+		// Default scope: filter by orgId
+		const scope: ScopeFilter = { orgId: ctx.orgId }
+
+		// Check if write access is available
+		const canWrite = ctx.permissions.some(
+			(p) =>
+				permissionCovers(p, `${collection}:write` as Permission) ||
+				permissionCovers(p, '*:write' as Permission),
+		)
+		if (!canWrite) {
+			scope.__readonly = true
+		}
+
+		return scope
+	}
+}

package/src/react/AuthProvider.tsx

@@ -0,0 +1,97 @@
+import { createElement, useEffect, useMemo, useSyncExternalStore } from 'react'
+import type { ReactElement, ReactNode } from 'react'
+import { createAuthSession } from '../bindings/create-auth-session'
+import type { AuthSession } from '../bindings/create-auth-session'
+import type { AuthClient } from '../client/auth-client'
+import { AuthContext } from './auth-context'
+
+interface AuthProviderProps {
+	client: AuthClient
+	children: ReactNode
+	fallback?: ReactNode
+}
+
+type SessionEntry = {
+	session: AuthSession
+	refs: number
+	destroyTimer: ReturnType<typeof setTimeout> | null
+}
+
+const sessionEntries = new WeakMap<AuthClient, SessionEntry>()
+
+function getSessionEntry(client: AuthClient): SessionEntry {
+	const existing = sessionEntries.get(client)
+	if (existing) return existing
+
+	const entry: SessionEntry = {
+		session: createAuthSession(client),
+		refs: 0,
+		destroyTimer: null,
+	}
+	sessionEntries.set(client, entry)
+	return entry
+}
+
+function retainSession(entry: SessionEntry): () => void {
+	if (entry.destroyTimer) {
+		clearTimeout(entry.destroyTimer)
+		entry.destroyTimer = null
+	}
+	entry.refs++
+
+	return () => {
+		entry.refs = Math.max(0, entry.refs - 1)
+		if (entry.refs > 0 || entry.destroyTimer) return
+
+		// React StrictMode intentionally runs effect cleanup and setup back-to-back
+		// on mount. Deferring disposal lets the second setup retain the same session,
+		// while a real unmount still releases the auth subscription shortly after.
+		entry.destroyTimer = setTimeout(() => {
+			entry.destroyTimer = null
+			if (entry.refs > 0) return
+			entry.session.destroy()
+			sessionEntries.delete(entry.session.client)
+		}, 0)
+	}
+}
+
+function AuthProvider({ client, children, fallback }: AuthProviderProps): ReactElement {
+	const entry = useMemo(() => getSessionEntry(client), [client])
+	const session = entry.session
+
+	useEffect(() => retainSession(entry), [entry])
+
+	const snapshot = useSyncExternalStore(
+		(onStoreChange) => session.subscribe(onStoreChange),
+		() => session.getSnapshot(),
+		() => session.getSnapshot(),
+	)
+
+	if (snapshot.initError) {
+		return createElement(
+			'div',
+			{
+				style: { color: 'red', padding: '1rem', fontFamily: 'monospace' },
+				role: 'alert',
+			},
+			createElement('strong', null, 'Kora Auth initialization error: '),
+			snapshot.initError.message,
+		)
+	}
+
+	if (snapshot.isLoading && fallback !== undefined) {
+		return fallback as ReactElement
+	}
+
+	const contextValue = {
+		client,
+		session,
+		state: snapshot.state,
+		isLoading: snapshot.isLoading,
+	}
+
+	return createElement(AuthContext.Provider, { value: contextValue }, children)
+}
+
+export { AuthProvider }
+export type { AuthProviderProps }

package/src/react/OrgProvider.tsx

@@ -0,0 +1,41 @@
+import { type ReactNode, useEffect, useMemo, useRef } from 'react'
+import { type OrgSession, createOrgSession } from '../bindings/create-org-session'
+import type { OrgClient } from '../client/org-client'
+import { OrgContext, type OrgContextValue } from './org-hooks'
+
+export interface OrgProviderProps {
+	client: OrgClient
+	children?: ReactNode
+}
+
+/**
+ * Provides organization context for {@link useOrg}, {@link useOrgMembers}, and {@link usePermission}.
+ */
+export function OrgProvider({ client, children }: OrgProviderProps) {
+	const sessionRef = useRef<OrgSession | null>(null)
+
+	if (sessionRef.current === null || sessionRef.current.client !== client) {
+		sessionRef.current?.destroy()
+		sessionRef.current = createOrgSession(client)
+	}
+
+	useEffect(() => {
+		return () => {
+			sessionRef.current?.destroy()
+			sessionRef.current = null
+		}
+	}, [])
+
+	const session = sessionRef.current
+	const value = useMemo<OrgContextValue>(
+		() => ({
+			client,
+			session,
+		}),
+		[client, session],
+	)
+
+	return <OrgContext.Provider value={value}>{children}</OrgContext.Provider>
+}
+
+export type { OrgContextValue }

package/src/react/auth-context.ts

@@ -0,0 +1,26 @@
+import { createContext } from 'react'
+import type { AuthSession } from '../bindings/create-auth-session'
+import type { AuthClient } from '../client/auth-client'
+
+/**
+ * Possible authentication states for the client.
+ */
+type AuthState = 'loading' | 'authenticated' | 'unauthenticated'
+
+/**
+ * Shape of the value provided by the AuthContext.
+ */
+interface AuthContextValue {
+	client: AuthClient
+	session: AuthSession
+	state: AuthState
+	isLoading: boolean
+}
+
+/**
+ * React context for Kora authentication.
+ */
+const AuthContext = createContext<AuthContextValue | null>(null)
+
+export { AuthContext }
+export type { AuthContextValue, AuthState }

package/src/react/hooks.ts

@@ -0,0 +1,110 @@
+import { useContext, useSyncExternalStore } from 'react'
+import type {
+	AuthState,
+	AuthUser,
+	LinkedOAuthAccount,
+	OAuthAuthorizationOptions,
+	OAuthAuthorizationResult,
+	OAuthCallbackParams,
+} from '../client/auth-client'
+import { AuthContext } from './auth-context'
+
+function useAuthContext() {
+	const ctx = useContext(AuthContext)
+	if (ctx === null) {
+		throw new Error(
+			'useAuth / useCurrentUser / useAuthStatus must be used within an <AuthProvider>. ' +
+				'Wrap your component tree with <AuthProvider client={authClient}>.',
+		)
+	}
+	return ctx
+}
+
+interface UseAuthResult {
+	user: AuthUser | null
+	isAuthenticated: boolean
+	isLoading: boolean
+	signUp: (params: {
+		email: string
+		password: string
+		name?: string
+		deviceId?: string
+		devicePublicKey?: string
+	}) => Promise<void>
+	signIn: (params: {
+		email: string
+		password: string
+		deviceId?: string
+		devicePublicKey?: string
+	}) => Promise<void>
+	signInWithOAuth: (
+		provider: string,
+		options?: OAuthAuthorizationOptions,
+	) => Promise<OAuthAuthorizationResult>
+	completeOAuthSignIn: (provider: string, params: OAuthCallbackParams) => Promise<void>
+	getOAuthAuthorizationUrl: (
+		provider: string,
+		options?: OAuthAuthorizationOptions,
+	) => Promise<OAuthAuthorizationResult>
+	linkOAuth: (provider: string, params: OAuthCallbackParams) => Promise<LinkedOAuthAccount | null>
+	listLinkedAccounts: () => Promise<LinkedOAuthAccount[]>
+	unlinkOAuth: (provider: string) => Promise<void>
+	signOut: () => Promise<void>
+	error: string | null
+	initError: Error | null
+}
+
+interface AuthStatus {
+	state: AuthState
+	isAuthenticated: boolean
+	isLoading: boolean
+}
+
+function useAuthSessionSnapshot() {
+	const { session } = useAuthContext()
+
+	return useSyncExternalStore(
+		(onStoreChange) => session.subscribe(onStoreChange),
+		() => session.getSnapshot(),
+		() => session.getSnapshot(),
+	)
+}
+
+function useAuth(): UseAuthResult {
+	const { session } = useAuthContext()
+	const snapshot = useAuthSessionSnapshot()
+
+	return {
+		user: snapshot.user,
+		isAuthenticated: snapshot.isAuthenticated,
+		isLoading: snapshot.isLoading,
+		error: snapshot.error,
+		initError: snapshot.initError,
+		signUp: (params) => session.signUp(params),
+		signIn: (params) => session.signIn(params),
+		signInWithOAuth: (provider, options) => session.signInWithOAuth(provider, options),
+		completeOAuthSignIn: (provider, params) => session.completeOAuthSignIn(provider, params),
+		getOAuthAuthorizationUrl: (provider, options) =>
+			session.getOAuthAuthorizationUrl(provider, options),
+		linkOAuth: (provider, params) => session.linkOAuth(provider, params),
+		listLinkedAccounts: () => session.listLinkedAccounts(),
+		unlinkOAuth: (provider) => session.unlinkOAuth(provider),
+		signOut: () => session.signOut(),
+	}
+}
+
+function useCurrentUser(): AuthUser | null {
+	return useAuthSessionSnapshot().user
+}
+
+function useAuthStatus(): AuthStatus {
+	const snapshot = useAuthSessionSnapshot()
+	return {
+		state: snapshot.state,
+		isAuthenticated: snapshot.isAuthenticated,
+		isLoading: snapshot.isLoading,
+	}
+}
+
+export { useAuth, useCurrentUser, useAuthStatus }
+export type { UseAuthResult, AuthStatus }