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

package/src/client/auth-sync.ts

@@ -0,0 +1,213 @@
+import {
+	type SchemaDefinition,
+	type ScopeMap,
+	buildScopeMap,
+	extractScopeValuesFromClaims,
+} from '@korajs/core'
+import type { AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings'
+import type { AuthClientSession, AuthState } from './auth-client'
+
+/**
+ * Minimal auth client surface required for sync integration.
+ * Matches {@link AuthClient} without importing implementation details.
+ */
+export interface AuthSyncClient {
+	getAccessToken(): Promise<string | null>
+	/**
+	 * Force a refresh even if the cached token looks valid locally. Called after
+	 * the sync server ends a session with `AUTH_EXPIRED` / `AUTH_REVOKED`.
+	 */
+	refreshAccessToken?(): Promise<string | null>
+	readonly state?: AuthState
+	onAuthChange?(callback: (state: AuthState) => void): () => void
+	/** Stored session freshness (authenticated-offline support). */
+	readonly session?: AuthClientSession | null
+	/** Unverified claims of the stored credentials, available offline. */
+	getStoredClaims?(): Promise<Record<string, unknown> | null>
+	/** Notifies when session freshness changes (fresh, offline, locked). */
+	onSessionChange?(callback: (session: AuthClientSession | null) => void): () => void
+}
+
+/**
+ * Sync binding returned by {@link createKoraAuthSync}.
+ * Passed to `createApp({ sync: { authClient } })` in korajs.
+ *
+ * @deprecated Use {@link AuthSyncBinding} from `@korajs/core/bindings` or `@korajs/auth`.
+ */
+export type KoraAuthSyncBinding = AuthSyncBinding
+
+/**
+ * Configuration for {@link createKoraAuthSync}.
+ */
+export interface CreateKoraAuthSyncOptions {
+	/** Kora auth client from `createKoraAuth()`. */
+	authClient: AuthSyncClient
+	/**
+	 * Application schema. When provided, a client-side scope hint is built from
+	 * token claims and schema scope declarations. The server only uses it to
+	 * NARROW its own grant; it never authorizes anything.
+	 */
+	schema?: SchemaDefinition
+	/**
+	 * Custom claim → flat scope value mapping.
+	 * Defaults to {@link extractScopeValuesFromClaims}.
+	 */
+	scopeFromClaims?: (claims: Record<string, unknown>) => Record<string, unknown>
+	/** Signed-out behavior. Authenticated-only sync is suspended by default. */
+	anonymous?: 'suspend' | 'allow'
+}
+
+/**
+ * Decode JWT payload without signature verification (client-side scope hints only).
+ */
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+	const parts = token.split('.')
+	if (parts.length !== 3) {
+		return null
+	}
+
+	const payloadSegment = parts[1]
+	if (payloadSegment === undefined) {
+		return null
+	}
+
+	try {
+		const base64 = payloadSegment.replace(/-/g, '+').replace(/_/g, '/')
+		const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=')
+		const json =
+			typeof atob === 'function' ? atob(padded) : Buffer.from(padded, 'base64').toString('utf-8')
+		const parsed: unknown = JSON.parse(json)
+		if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+			return null
+		}
+		return parsed as Record<string, unknown>
+	} catch {
+		return null
+	}
+}
+
+function readString(claims: Record<string, unknown> | null, key: string): string | undefined {
+	const value = claims?.[key]
+	return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * Creates a sync auth binding for `createApp({ sync: { authClient: binding } })`.
+ *
+ * Wires token refresh, a client-side scope hint, and device-bound sync node ids
+ * (`dev` claim) separate from the user id (`sub`).
+ *
+ * Offline-first: identity (user id, device id) comes from the stored session,
+ * not from token freshness. While the auth server is unreachable the binding
+ * keeps reporting the signed-in user (authenticated-offline, `token: null`), so
+ * the user's own local database opens and the app stays usable; only the sync
+ * transport waits for a fresh token.
+ *
+ * @example
+ * ```typescript
+ * import { createKoraAuth, createKoraAuthSync } from '@korajs/auth'
+ * import { createApp } from 'korajs'
+ *
+ * const authClient = createKoraAuth({ serverUrl: 'https://api.example.com' })
+ *
+ * const app = createApp({
+ *   schema,
+ *   sync: {
+ *     url: 'wss://api.example.com/kora-sync',
+ *     authClient: createKoraAuthSync({ authClient, schema }),
+ *   },
+ * })
+ * ```
+ */
+export function createKoraAuthSync(options: CreateKoraAuthSyncOptions): AuthSyncBinding {
+	const { authClient, schema, scopeFromClaims, anonymous = 'suspend' } = options
+
+	/**
+	 * Claims of the session: from a fresh token when one can be minted, else from
+	 * the stored credentials while the client is still signed in.
+	 */
+	const resolveClaims = async (): Promise<{
+		claims: Record<string, unknown> | null
+		token: string | null
+	}> => {
+		const token = await authClient.getAccessToken()
+		if (token) return { claims: decodeJwtPayload(token), token }
+		if (authClient.state === 'unauthenticated' || !authClient.getStoredClaims) {
+			return { claims: null, token: null }
+		}
+		return { claims: await authClient.getStoredClaims(), token: null }
+	}
+
+	const binding: AuthSyncBinding = {
+		auth: async (request) => {
+			// After the server ended the session for an expired or revoked credential,
+			// the cached token is known bad: refresh instead of re-presenting it.
+			const token =
+				request?.forceRefresh && authClient.refreshAccessToken
+					? await authClient.refreshAccessToken()
+					: await authClient.getAccessToken()
+			return { token: token ?? '' }
+		},
+	}
+
+	binding.resolveSyncState = async (): Promise<AuthSyncState> => {
+		if (authClient.state === 'loading') return { state: 'loading' }
+		const { claims, token } = await resolveClaims()
+		const userId = readString(claims, 'sub')
+		if (!userId) {
+			return anonymous === 'allow'
+				? { state: 'anonymous', mayConnectAnonymously: true }
+				: { state: 'signed-out', mayConnectAnonymously: false }
+		}
+		const deviceId = readString(claims, 'dev')
+		if (token) {
+			return { state: 'authenticated', userId, token, ...(deviceId ? { deviceId } : {}) }
+		}
+		return {
+			state: 'authenticated',
+			userId,
+			token: null,
+			offline: true,
+			locked: authClient.session?.status === 'locked',
+			...(deviceId ? { deviceId } : {}),
+		}
+	}
+
+	if (schema) {
+		binding.resolveScopeMap = async () => {
+			const { claims } = await resolveClaims()
+			if (!claims) {
+				return undefined
+			}
+
+			const scopeValues = scopeFromClaims
+				? scopeFromClaims(claims)
+				: extractScopeValuesFromClaims(schema, claims)
+
+			return buildScopeMap(schema, scopeValues) as ScopeMap
+		}
+	}
+
+	binding.resolveNodeId = async () => {
+		const { claims } = await resolveClaims()
+		return readString(claims, 'dev')
+	}
+
+	binding.resolveUserId = async () => {
+		const { claims } = await resolveClaims()
+		return readString(claims, 'sub')
+	}
+
+	if (authClient.onAuthChange || authClient.onSessionChange) {
+		binding.subscribe = (listener) => {
+			const offAuth = authClient.onAuthChange?.(() => listener()) ?? (() => {})
+			const offSession = authClient.onSessionChange?.(() => listener()) ?? (() => {})
+			return () => {
+				offAuth()
+				offSession()
+			}
+		}
+	}
+
+	return binding
+}

package/src/client/device-session.ts

@@ -0,0 +1,104 @@
+import { KoraError } from '@korajs/core'
+import { exportPublicKeyJwk, generateDeviceKeyPair } from '../device/device-identity'
+import { type DeviceKeyStore, createDeviceKeyStore } from '../device/device-store'
+import type { AuthKeyValueStorage } from './storage'
+
+const DEFAULT_DEVICE_ID_KEY = 'kora_auth_device_id'
+
+export interface AuthDeviceIdentity {
+	/** Stable local device ID used in token `dev` claims. */
+	deviceId: string
+	/** Public proof-of-possession key serialized as a JSON Web Key string. */
+	devicePublicKey: string
+}
+
+export interface AuthDeviceIdentityProvider {
+	getDeviceIdentity(): Promise<AuthDeviceIdentity>
+}
+
+export interface PersistentDeviceIdentityOptions {
+	/** Store for the stable device ID. Use a platform credential store in production. */
+	storage: AuthKeyValueStorage
+	/** Store for the non-extractable device key pair. Defaults to IndexedDB when available. */
+	keyStore?: DeviceKeyStore
+	/** Storage key for the device ID. Defaults to `kora_auth_device_id`. */
+	deviceIdKey?: string
+	/** Optional device ID generator for tests or custom device registries. */
+	generateDeviceId?: () => string
+}
+
+export class AuthDeviceIdentityError extends KoraError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, 'AUTH_DEVICE_IDENTITY_ERROR', context)
+		this.name = 'AuthDeviceIdentityError'
+	}
+}
+
+/**
+ * Creates a persistent device identity provider for `AuthClient`.
+ *
+ * The provider keeps a stable device ID in the supplied key-value store and a
+ * non-extractable ECDSA P-256 key pair in the supplied `DeviceKeyStore`. The
+ * public key is returned during sign-up/sign-in so the server can bind tokens
+ * to a real offline device instead of a transient browser session.
+ */
+export function createPersistentDeviceIdentity(
+	options: PersistentDeviceIdentityOptions,
+): AuthDeviceIdentityProvider {
+	const storage = options.storage
+	const keyStore = options.keyStore ?? createDefaultPersistentKeyStore()
+	const deviceIdKey = options.deviceIdKey ?? DEFAULT_DEVICE_ID_KEY
+	const generateDeviceId = options.generateDeviceId ?? defaultDeviceId
+
+	return {
+		async getDeviceIdentity(): Promise<AuthDeviceIdentity> {
+			let deviceId = await storage.getItem(deviceIdKey)
+			if (!deviceId) {
+				deviceId = generateDeviceId()
+				await storage.setItem(deviceIdKey, deviceId)
+			}
+
+			let keyPair = await keyStore.loadKeyPair(deviceId)
+			if (!keyPair) {
+				keyPair = await generateDeviceKeyPair()
+				await keyStore.saveKeyPair(deviceId, keyPair)
+			}
+
+			const publicKey = await exportPublicKeyJwk(keyPair)
+			return {
+				deviceId,
+				devicePublicKey: JSON.stringify(publicKey),
+			}
+		},
+	}
+}
+
+function createDefaultPersistentKeyStore(): DeviceKeyStore {
+	if (typeof globalThis.indexedDB !== 'undefined') {
+		return createDeviceKeyStore()
+	}
+
+	throw new AuthDeviceIdentityError(
+		'No persistent device key store is available in this runtime. Pass `keyStore` to createPersistentDeviceIdentity().',
+	)
+}
+
+function defaultDeviceId(): string {
+	if (typeof globalThis.crypto?.randomUUID === 'function') {
+		return globalThis.crypto.randomUUID()
+	}
+
+	const bytes = new Uint8Array(16)
+	if (typeof globalThis.crypto?.getRandomValues === 'function') {
+		globalThis.crypto.getRandomValues(bytes)
+	} else {
+		for (let i = 0; i < bytes.length; i++) {
+			bytes[i] = Math.floor(Math.random() * 256)
+		}
+	}
+
+	bytes[6] = ((bytes[6] as number) & 0x0f) | 0x40
+	bytes[8] = ((bytes[8] as number) & 0x3f) | 0x80
+	const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}

package/src/client/org-client.ts

@@ -0,0 +1,399 @@
+import { KoraError } from '@korajs/core'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Organization info returned by the server.
+ */
+export interface ClientOrganization {
+	id: string
+	name: string
+	slug: string
+	ownerId: string
+	createdAt: number
+	updatedAt: number
+	metadata: Record<string, unknown>
+}
+
+/**
+ * Membership info returned by the server.
+ */
+export interface ClientMembership {
+	id: string
+	orgId: string
+	userId: string
+	role: string
+	invitedBy: string | null
+	joinedAt: number
+}
+
+/**
+ * Invitation info returned by the server.
+ */
+export interface ClientInvitation {
+	id: string
+	orgId: string
+	email: string
+	role: string
+	invitedBy: string
+	token: string
+	createdAt: number
+	expiresAt: number
+	status: string
+}
+
+/**
+ * Configuration for the OrgClient.
+ */
+export interface OrgClientConfig {
+	/** Base URL of the auth/org server */
+	serverUrl: string
+	/** Function that returns a valid access token for authenticated requests */
+	getAccessToken: () => Promise<string | null>
+}
+
+/**
+ * Thrown when an org operation fails.
+ */
+export class OrgClientError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'OrgClientError'
+	}
+}
+
+// ============================================================================
+// OrgClient
+// ============================================================================
+
+/**
+ * Client-side organization manager.
+ *
+ * Handles org CRUD, member management, invitations, and active org switching.
+ * Framework-agnostic — works in any JavaScript environment with `fetch`.
+ *
+ * @example
+ * ```typescript
+ * const orgClient = new OrgClient({
+ *   serverUrl: 'http://localhost:3001',
+ *   getAccessToken: () => authClient.getAccessToken(),
+ * })
+ *
+ * const org = await orgClient.createOrg({ name: 'Acme Inc', slug: 'acme' })
+ * orgClient.switchOrg(org.id)
+ * ```
+ */
+export class OrgClient {
+	private readonly serverUrl: string
+	private readonly getAccessToken: () => Promise<string | null>
+	private readonly listeners = new Set<(orgId: string | null) => void>()
+
+	private _activeOrgId: string | null = null
+	private _activeOrg: ClientOrganization | null = null
+	private _activeRole: string | null = null
+
+	constructor(config: OrgClientConfig) {
+		this.serverUrl = config.serverUrl.replace(/\/+$/, '')
+		this.getAccessToken = config.getAccessToken
+	}
+
+	// --- Getters ---
+
+	/** Currently active organization ID */
+	get activeOrgId(): string | null {
+		return this._activeOrgId
+	}
+
+	/** Currently active organization */
+	get activeOrg(): ClientOrganization | null {
+		return this._activeOrg
+	}
+
+	/** Current user's role in the active organization */
+	get activeRole(): string | null {
+		return this._activeRole
+	}
+
+	// --- Organization Operations ---
+
+	/**
+	 * Create a new organization.
+	 */
+	async createOrg(params: {
+		name: string
+		slug?: string
+		metadata?: Record<string, unknown>
+	}): Promise<ClientOrganization> {
+		return this.request<ClientOrganization>('/orgs', {
+			method: 'POST',
+			body: params,
+		})
+	}
+
+	/**
+	 * List all organizations the current user belongs to.
+	 */
+	async listOrgs(): Promise<ClientOrganization[]> {
+		return this.request<ClientOrganization[]>('/orgs', { method: 'GET' })
+	}
+
+	/**
+	 * Get an organization by ID.
+	 */
+	async getOrg(orgId: string): Promise<ClientOrganization> {
+		return this.request<ClientOrganization>(`/orgs/${orgId}`, { method: 'GET' })
+	}
+
+	/**
+	 * Update an organization.
+	 */
+	async updateOrg(
+		orgId: string,
+		params: { name?: string; slug?: string; metadata?: Record<string, unknown> },
+	): Promise<ClientOrganization> {
+		const result = await this.request<ClientOrganization>(`/orgs/${orgId}`, {
+			method: 'PATCH',
+			body: params,
+		})
+		// Update cached active org if this is the active one
+		if (this._activeOrgId === orgId) {
+			this._activeOrg = result
+		}
+		return result
+	}
+
+	/**
+	 * Delete an organization.
+	 */
+	async deleteOrg(orgId: string): Promise<void> {
+		await this.request(`/orgs/${orgId}`, { method: 'DELETE' })
+		if (this._activeOrgId === orgId) {
+			this._activeOrgId = null
+			this._activeOrg = null
+			this._activeRole = null
+			this.notifyListeners()
+		}
+	}
+
+	// --- Org Switching ---
+
+	/**
+	 * Switch the active organization context.
+	 * Fetches the org details and the user's membership/role.
+	 */
+	async switchOrg(orgId: string): Promise<void> {
+		const org = await this.request<ClientOrganization>(`/orgs/${orgId}`, { method: 'GET' })
+		const membership = await this.request<ClientMembership>(`/orgs/${orgId}/membership`, {
+			method: 'GET',
+		})
+
+		this._activeOrgId = orgId
+		this._activeOrg = org
+		this._activeRole = membership.role
+		this.notifyListeners()
+	}
+
+	/**
+	 * Clear the active organization (no org selected).
+	 */
+	clearActiveOrg(): void {
+		this._activeOrgId = null
+		this._activeOrg = null
+		this._activeRole = null
+		this.notifyListeners()
+	}
+
+	// --- Member Management ---
+
+	/**
+	 * List members of an organization.
+	 */
+	async listMembers(orgId: string): Promise<ClientMembership[]> {
+		return this.request<ClientMembership[]>(`/orgs/${orgId}/members`, { method: 'GET' })
+	}
+
+	/**
+	 * Remove a member from an organization.
+	 */
+	async removeMember(orgId: string, userId: string): Promise<void> {
+		await this.request(`/orgs/${orgId}/members/${userId}`, { method: 'DELETE' })
+	}
+
+	/**
+	 * Update a member's role.
+	 */
+	async updateMemberRole(orgId: string, userId: string, role: string): Promise<ClientMembership> {
+		return this.request<ClientMembership>(`/orgs/${orgId}/members/${userId}/role`, {
+			method: 'PATCH',
+			body: { role },
+		})
+	}
+
+	/**
+	 * Transfer ownership to another member.
+	 */
+	async transferOwnership(orgId: string, newOwnerId: string): Promise<void> {
+		await this.request(`/orgs/${orgId}/transfer`, {
+			method: 'POST',
+			body: { newOwnerId },
+		})
+	}
+
+	/**
+	 * Leave an organization (remove yourself).
+	 */
+	async leaveOrg(orgId: string): Promise<void> {
+		await this.request(`/orgs/${orgId}/leave`, { method: 'POST' })
+		if (this._activeOrgId === orgId) {
+			this._activeOrgId = null
+			this._activeOrg = null
+			this._activeRole = null
+			this.notifyListeners()
+		}
+	}
+
+	// --- Invitations ---
+
+	/**
+	 * Invite a user to an organization by email.
+	 */
+	async inviteMember(
+		orgId: string,
+		params: { email: string; role: string },
+	): Promise<ClientInvitation> {
+		return this.request<ClientInvitation>(`/orgs/${orgId}/invitations`, {
+			method: 'POST',
+			body: params,
+		})
+	}
+
+	/**
+	 * Accept an invitation by token.
+	 */
+	async acceptInvitation(token: string): Promise<ClientMembership> {
+		return this.request<ClientMembership>('/invitations/accept', {
+			method: 'POST',
+			body: { token },
+		})
+	}
+
+	/**
+	 * List pending invitations for an organization.
+	 */
+	async listInvitations(orgId: string): Promise<ClientInvitation[]> {
+		return this.request<ClientInvitation[]>(`/orgs/${orgId}/invitations`, { method: 'GET' })
+	}
+
+	/**
+	 * Revoke a pending invitation.
+	 */
+	async revokeInvitation(orgId: string, invitationId: string): Promise<void> {
+		await this.request(`/orgs/${orgId}/invitations/${invitationId}`, { method: 'DELETE' })
+	}
+
+	/**
+	 * List pending invitations addressed to the signed-in user's verified email.
+	 * The server resolves the email from the session; tokens are never returned.
+	 */
+	async listMyInvitations(): Promise<Array<Omit<ClientInvitation, 'token'>>> {
+		return this.request<Array<Omit<ClientInvitation, 'token'>>>('/invitations', {
+			method: 'GET',
+		})
+	}
+
+	// --- Subscriptions ---
+
+	/**
+	 * Subscribe to active org changes.
+	 * @returns Unsubscribe function
+	 */
+	onOrgChange(callback: (orgId: string | null) => void): () => void {
+		this.listeners.add(callback)
+		return () => {
+			this.listeners.delete(callback)
+		}
+	}
+
+	// --- Internal ---
+
+	private notifyListeners(): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(this._activeOrgId)
+			} catch {
+				// Don't let listener errors break the notification loop
+			}
+		}
+	}
+
+	private async request<T = void>(
+		path: string,
+		options: {
+			method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+			body?: Record<string, unknown>
+		},
+	): Promise<T> {
+		const token = await this.getAccessToken()
+		if (!token) {
+			throw new OrgClientError(
+				'Not authenticated. Sign in before performing organization operations.',
+				'ORG_NOT_AUTHENTICATED',
+			)
+		}
+
+		const url = `${this.serverUrl}${path}`
+		const headers: Record<string, string> = {
+			Authorization: `Bearer ${token}`,
+		}
+		if (options.body) {
+			headers['Content-Type'] = 'application/json'
+		}
+
+		let response: Response
+		try {
+			response = await fetch(url, {
+				method: options.method,
+				headers,
+				body: options.body ? JSON.stringify(options.body) : undefined,
+			})
+		} catch (cause) {
+			throw new OrgClientError(`Network request to ${path} failed.`, 'ORG_NETWORK_ERROR', {
+				path,
+				cause: cause instanceof Error ? cause.message : String(cause),
+			})
+		}
+
+		if (!response.ok) {
+			let errorMessage = `Server returned HTTP ${response.status}`
+			try {
+				const body = (await response.json()) as Record<string, unknown>
+				if (typeof body.error === 'string') {
+					errorMessage = body.error as string
+				}
+			} catch {
+				// not JSON
+			}
+			throw new OrgClientError(errorMessage, 'ORG_SERVER_ERROR', {
+				path,
+				status: response.status,
+			})
+		}
+
+		// Handle empty responses (DELETE, etc.)
+		const text = await response.text()
+		if (text.length === 0) return undefined as T
+
+		try {
+			const body = JSON.parse(text)
+			// Unwrap { data: ... } envelope if present
+			if (body && typeof body === 'object' && 'data' in body) {
+				return body.data as T
+			}
+			return body as T
+		} catch {
+			return undefined as T
+		}
+	}
+}