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

package/src/tokens/token-store.ts

@@ -0,0 +1,192 @@
+import type { AuthTokens } from '../types'
+
+/** Default key used for localStorage persistence. */
+const DEFAULT_STORAGE_KEY = 'kora_auth_tokens'
+
+/**
+ * Minimal storage interface matching the subset of the Web Storage API
+ * that TokenStore needs. This allows both localStorage and in-memory
+ * implementations to be used interchangeably.
+ */
+interface SimpleStorage {
+	getItem(key: string): string | null
+	setItem(key: string, value: string): void
+	removeItem(key: string): void
+}
+
+/**
+ * In-memory storage fallback used when localStorage is unavailable
+ * (e.g., in Node.js, SSR environments, or when storage access is denied).
+ */
+class MemoryStorage implements SimpleStorage {
+	private store = new Map<string, string>()
+
+	getItem(key: string): string | null {
+		return this.store.get(key) ?? null
+	}
+
+	setItem(key: string, value: string): void {
+		this.store.set(key, value)
+	}
+
+	removeItem(key: string): void {
+		this.store.delete(key)
+	}
+}
+
+/**
+ * Attempts to access localStorage. Returns null if unavailable.
+ *
+ * localStorage may be unavailable in several scenarios:
+ * - Node.js / server-side rendering (no window object)
+ * - Private browsing modes with restricted storage
+ * - iframe sandboxing without storage access
+ * - User has disabled cookies/storage in browser settings
+ */
+function tryGetLocalStorage(): SimpleStorage | null {
+	try {
+		if (typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
+			const storage = globalThis.localStorage as SimpleStorage
+			// Probe that read/write actually works (some browsers throw on access)
+			const testKey = '__kora_storage_test__'
+			storage.setItem(testKey, '1')
+			storage.removeItem(testKey)
+			return storage
+		}
+	} catch {
+		// localStorage exists but access is denied (e.g., private mode in some browsers)
+	}
+	return null
+}
+
+/**
+ * Client-side token storage for Kora auth tokens.
+ *
+ * Persists tokens to localStorage when available, falling back to in-memory
+ * storage in environments where localStorage is unavailable (Node.js, SSR,
+ * restricted browser contexts). Encrypted storage is planned for Phase 2.
+ *
+ * All operations are synchronous since both localStorage and in-memory
+ * storage are synchronous.
+ *
+ * @example
+ * ```typescript
+ * const store = new TokenStore()
+ *
+ * // After login
+ * store.saveTokens({ accessToken: '...', refreshToken: '...' })
+ *
+ * // Before API calls
+ * const token = store.getAccessToken()
+ *
+ * // On logout
+ * store.clearTokens()
+ * ```
+ */
+export class TokenStore {
+	private readonly storageKey: string
+	private readonly storage: SimpleStorage
+
+	/**
+	 * Creates a new TokenStore instance.
+	 *
+	 * @param storageKey - The key under which tokens are stored. Defaults to 'kora_auth_tokens'.
+	 *   Use different keys if your app runs multiple Kora instances with separate auth.
+	 */
+	constructor(storageKey?: string) {
+		this.storageKey = storageKey ?? DEFAULT_STORAGE_KEY
+		this.storage = tryGetLocalStorage() ?? new MemoryStorage()
+	}
+
+	/**
+	 * Save tokens to persistent storage.
+	 *
+	 * Overwrites any previously stored tokens. The tokens are serialized
+	 * as JSON. Only the `accessToken`, `refreshToken`, and optional
+	 * `deviceCredential` fields are persisted.
+	 *
+	 * @param tokens - The token set to store
+	 */
+	saveTokens(tokens: AuthTokens): void {
+		const serialized: AuthTokens = {
+			accessToken: tokens.accessToken,
+			refreshToken: tokens.refreshToken,
+		}
+		if (tokens.deviceCredential !== undefined) {
+			serialized.deviceCredential = tokens.deviceCredential
+		}
+		this.storage.setItem(this.storageKey, JSON.stringify(serialized))
+	}
+
+	/**
+	 * Load tokens from storage.
+	 *
+	 * @returns The stored {@link AuthTokens}, or null if no tokens have been saved
+	 */
+	loadTokens(): AuthTokens | null {
+		const raw = this.storage.getItem(this.storageKey)
+		if (raw === null) {
+			return null
+		}
+
+		try {
+			const parsed: unknown = JSON.parse(raw)
+			if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+				return null
+			}
+			const record = parsed as Record<string, unknown>
+
+			// Validate required fields are present and are strings
+			if (typeof record.accessToken !== 'string' || typeof record.refreshToken !== 'string') {
+				return null
+			}
+
+			const tokens: AuthTokens = {
+				accessToken: record.accessToken,
+				refreshToken: record.refreshToken,
+			}
+
+			if (typeof record.deviceCredential === 'string') {
+				tokens.deviceCredential = record.deviceCredential
+			}
+
+			return tokens
+		} catch {
+			// Corrupted data in storage; treat as empty
+			return null
+		}
+	}
+
+	/**
+	 * Clear all stored tokens.
+	 *
+	 * Call this on logout to remove credentials from persistent storage.
+	 */
+	clearTokens(): void {
+		this.storage.removeItem(this.storageKey)
+	}
+
+	/**
+	 * Get the current access token.
+	 *
+	 * Returns the raw token string without validating expiration.
+	 * The caller is responsible for checking whether the token is
+	 * still valid and initiating a refresh if needed.
+	 *
+	 * @returns The access token string, or null if no tokens are stored
+	 */
+	getAccessToken(): string | null {
+		const tokens = this.loadTokens()
+		return tokens?.accessToken ?? null
+	}
+
+	/**
+	 * Get the current refresh token.
+	 *
+	 * @returns The refresh token string, or null if no tokens are stored
+	 */
+	getRefreshToken(): string | null {
+		const tokens = this.loadTokens()
+		return tokens?.refreshToken ?? null
+	}
+}

package/src/types.ts

@@ -0,0 +1,394 @@
+import { KoraError } from '@korajs/core'
+
+// ============================================================================
+// User types
+// ============================================================================
+
+/**
+ * Authenticated user record.
+ * Represents the public-facing user identity returned by sign-in and sign-up flows.
+ */
+export interface AuthUser {
+	/** Unique user identifier (UUID v7) */
+	id: string
+	/** User's email address, used as the primary login credential */
+	email: string
+	/** Display name */
+	name: string
+	/** Timestamp of user creation (milliseconds since epoch) */
+	createdAt: number
+	/** Timestamp of last profile update (milliseconds since epoch) */
+	updatedAt: number
+}
+
+/**
+ * A registered device that can operate on behalf of a user.
+ * Each device has its own keypair for offline credential verification.
+ */
+export interface AuthDevice {
+	/** Device identifier, same as the Kora nodeId for this device */
+	id: string
+	/** The user this device belongs to */
+	userId: string
+	/** JWK-encoded public key for this device's keypair */
+	publicKey: string
+	/** Human-readable device name (e.g., "Chrome on MacBook") */
+	name: string
+	/** Timestamp when the device was first registered (milliseconds since epoch) */
+	registeredAt: number
+	/** Timestamp of last activity from this device (milliseconds since epoch) */
+	lastSeenAt: number
+	/** Whether this device is allowed to sync */
+	status: DeviceStatus
+}
+
+/** Device status values */
+export type DeviceStatus = 'active' | 'revoked'
+
+// ============================================================================
+// Token types
+// ============================================================================
+
+/** The three kinds of tokens issued by the auth system */
+export type TokenType = 'access' | 'refresh' | 'device_credential'
+
+/**
+ * Base payload present in all JWT tokens.
+ * Fields follow standard JWT claim names.
+ */
+export interface TokenPayload {
+	/** JWT ID: unique identifier for this specific token (for revocation and replay detection) */
+	jti: string
+	/** Subject: the user ID */
+	sub: string
+	/** Device ID that this token was issued to */
+	dev: string
+	/** Which kind of token this is */
+	type: TokenType
+	/** Issued-at time (seconds since epoch, per JWT spec) */
+	iat: number
+	/** Expiration time (seconds since epoch, per JWT spec) */
+	exp: number
+	/**
+	 * Refresh-token family id. Every token minted by one sign-in and its refresh
+	 * rotations shares it, so reuse detection can revoke exactly that family
+	 * instead of the whole device. Absent on tokens minted before beta.13.
+	 */
+	fam?: string
+	/**
+	 * Issue time in milliseconds. `iat` has one-second resolution, which is too
+	 * coarse to order a token against a revocation made in the same second.
+	 */
+	iatMs?: number
+	/**
+	 * Authentication methods used to obtain this session (RFC 8176), for example
+	 * `['pwd']` or `['pwd', 'otp']`.
+	 */
+	amr?: string[]
+}
+
+/**
+ * Short-lived token used to authenticate API requests.
+ * Typically lives for 15 minutes.
+ */
+export interface AccessTokenPayload extends TokenPayload {
+	type: 'access'
+}
+
+/**
+ * Longer-lived token used to obtain new access tokens.
+ * Typically lives for 90 days.
+ */
+export interface RefreshTokenPayload extends TokenPayload {
+	type: 'refresh'
+}
+
+/**
+ * Offline credential stored on the device.
+ * Allows the device to continue operating offline, with a mandatory
+ * check-in deadline by which it must reconnect to remain authorized.
+ */
+export interface DeviceCredentialPayload extends TokenPayload {
+	type: 'device_credential'
+	/** Device public key thumbprint, binds this credential to a specific device keypair */
+	dpk: string
+	/** Timestamp (seconds since epoch) by which the device must check in with the server */
+	mustCheckinBy: number
+}
+
+/**
+ * Bundle of tokens returned after successful authentication.
+ */
+export interface AuthTokens {
+	/** Short-lived access token */
+	accessToken: string
+	/** Long-lived refresh token */
+	refreshToken: string
+	/** Optional device credential for offline operation */
+	deviceCredential?: string
+}
+
+// ============================================================================
+// Auth configuration
+// ============================================================================
+
+/** Supported auth provider types */
+export type AuthProviderType = 'built-in' | 'custom'
+
+/** Unlock mechanism for encrypted local storage */
+export type UnlockMethod = 'biometric' | 'passphrase' | 'both'
+
+/**
+ * Encryption settings for locally stored auth credentials.
+ */
+export interface AuthEncryptionConfig {
+	/** Whether local credential encryption is enabled */
+	enabled: boolean
+	/** How the user unlocks encrypted credentials */
+	unlock: UnlockMethod
+	/** Milliseconds of inactivity before the app auto-locks. Defaults to 15 minutes. */
+	autoLockTimeout?: number
+}
+
+/**
+ * Custom lifetimes for each token type.
+ * All values are in milliseconds.
+ */
+export interface TokenLifetimeConfig {
+	/** Access token lifetime in ms. Default: 15 minutes. */
+	access?: number
+	/** Refresh token lifetime in ms. Default: 90 days. */
+	refresh?: number
+	/** Device credential lifetime in ms. Default: 90 days. */
+	deviceCredential?: number
+}
+
+/**
+ * Configuration for the Kora auth system.
+ * Passed to the auth initializer to control provider, encryption, and token behavior.
+ */
+export interface AuthConfig {
+	/** Which auth provider to use */
+	provider: AuthProviderType
+	/** Local encryption settings for stored credentials */
+	encryption?: AuthEncryptionConfig
+	/** Maximum time a device can operate offline without checking in (ms). Default: 30 days. */
+	maxOfflineDuration?: number
+	/** Custom token lifetimes */
+	tokenLifetimes?: TokenLifetimeConfig
+}
+
+// ============================================================================
+// Auth state
+// ============================================================================
+
+/** Possible authentication states */
+export type AuthStatus = 'authenticated' | 'unauthenticated' | 'locked'
+
+/**
+ * Current state of the auth system.
+ * This is the value exposed to the UI layer for rendering auth-dependent views.
+ */
+export interface AuthState {
+	/** Current authentication status */
+	status: AuthStatus
+	/** The authenticated user, or null if unauthenticated/locked */
+	user: AuthUser | null
+	/** The current device's ID, or null if not yet registered */
+	deviceId: string | null
+}
+
+// ============================================================================
+// Auth events
+// ============================================================================
+
+/**
+ * Events emitted by the auth system.
+ * These integrate with Kora's event system for DevTools observability.
+ */
+export type AuthEvent =
+	| { type: 'auth:signed-in'; user: AuthUser }
+	| { type: 'auth:signed-out' }
+	| { type: 'auth:locked' }
+	| { type: 'auth:unlocked'; user: AuthUser }
+	| { type: 'auth:token-refreshed' }
+	| { type: 'auth:device-revoked'; deviceId: string }
+	| { type: 'auth:permission-changed' }
+
+/** Extract the event type string union from AuthEvent */
+export type AuthEventType = AuthEvent['type']
+
+/** Extract a specific auth event by its type */
+export type AuthEventByType<T extends AuthEventType> = Extract<AuthEvent, { type: T }>
+
+// ============================================================================
+// Auth errors
+// ============================================================================
+
+/**
+ * Base error class for authentication-related failures.
+ * Extends KoraError to integrate with the framework's error handling patterns.
+ */
+export class AuthError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'AuthError'
+	}
+}
+
+/**
+ * Thrown when sign-in credentials are invalid (wrong email or password).
+ */
+export class InvalidCredentialsError extends AuthError {
+	constructor() {
+		super('Invalid email or password.', 'AUTH_INVALID_CREDENTIALS')
+		this.name = 'InvalidCredentialsError'
+	}
+}
+
+/**
+ * Thrown when a user tries to sign up with an email that already exists.
+ */
+export class EmailAlreadyExistsError extends AuthError {
+	constructor() {
+		super('An account with this email already exists.', 'AUTH_EMAIL_EXISTS')
+		this.name = 'EmailAlreadyExistsError'
+	}
+}
+
+/**
+ * Thrown when a token is expired, malformed, or has an invalid signature.
+ */
+export class TokenError extends AuthError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, 'AUTH_TOKEN_ERROR', context)
+		this.name = 'TokenError'
+	}
+}
+
+/**
+ * Thrown when a device's credential has expired or the device has been revoked.
+ */
+export class DeviceRevokedError extends AuthError {
+	constructor(deviceId: string) {
+		super(`Device "${deviceId}" has been revoked and can no longer sync.`, 'AUTH_DEVICE_REVOKED', {
+			deviceId,
+		})
+		this.name = 'DeviceRevokedError'
+	}
+}
+
+/**
+ * Thrown when the maximum offline duration has been exceeded
+ * and the device must reconnect to continue operating.
+ */
+export class OfflineExpiredError extends AuthError {
+	constructor(maxDuration: number, lastCheckin: number) {
+		const daysSinceCheckin = Math.round((Date.now() - lastCheckin) / (24 * 60 * 60 * 1000))
+		super(
+			`Device has been offline for ${daysSinceCheckin} days, exceeding the maximum offline duration. Reconnect to re-authenticate.`,
+			'AUTH_OFFLINE_EXPIRED',
+			{ maxDuration, lastCheckin, daysSinceCheckin },
+		)
+		this.name = 'OfflineExpiredError'
+	}
+}
+
+// ============================================================================
+// Sign up / sign in params
+// ============================================================================
+
+/**
+ * Parameters for creating a new user account.
+ */
+export interface SignUpParams {
+	/** Email address (used as login credential) */
+	email: string
+	/** Password (will be hashed before storage) */
+	password: string
+	/** Optional display name. Defaults to the local part of the email if omitted. */
+	name?: string
+}
+
+/**
+ * Parameters for signing in to an existing account.
+ */
+export interface SignInParams {
+	/** Email address */
+	email: string
+	/** Password */
+	password: string
+}
+
+// ============================================================================
+// Server-side types for the built-in provider
+// ============================================================================
+
+/**
+ * Parameters for creating a user record in the server-side store.
+ * The password has already been hashed by the time this is used.
+ */
+export interface CreateUserParams {
+	/** Email address */
+	email: string
+	/** Argon2id or bcrypt hash of the password */
+	passwordHash: string
+	/** Random salt used during hashing */
+	salt: string
+	/** Display name */
+	name: string
+}
+
+/**
+ * Full user record as stored on the server, including sensitive credential fields.
+ * This type must NEVER be returned to the client; strip passwordHash and salt first.
+ */
+export interface StoredUser extends AuthUser {
+	/** Hashed password */
+	passwordHash: string
+	/** Salt used for hashing */
+	salt: string
+}
+
+// ============================================================================
+// Auth provider adapter interface
+// ============================================================================
+
+/**
+ * Adapter interface for pluggable auth providers.
+ * Implement this to integrate Kora auth with a custom identity provider
+ * (e.g., Firebase Auth, Auth0, Supabase Auth).
+ *
+ * The built-in provider implements this interface internally.
+ */
+export interface AuthProviderAdapter {
+	/** Register a new user and return the user with initial tokens */
+	signUp(params: SignUpParams): Promise<{ user: AuthUser; tokens: AuthTokens }>
+	/** Authenticate an existing user and return the user with tokens */
+	signIn(params: SignInParams): Promise<{ user: AuthUser; tokens: AuthTokens }>
+	/** Exchange a refresh token for a new token set */
+	refreshToken(refreshToken: string): Promise<AuthTokens>
+	/** Validate an access token and return its payload, or null if invalid */
+	validateAccessToken(token: string): Promise<TokenPayload | null>
+	/** Revoke a device, preventing it from syncing */
+	revokeDevice(deviceId: string): Promise<void>
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default access token lifetime: 15 minutes */
+export const DEFAULT_ACCESS_TOKEN_LIFETIME = 15 * 60 * 1000
+
+/** Default refresh token lifetime: 90 days */
+export const DEFAULT_REFRESH_TOKEN_LIFETIME = 90 * 24 * 60 * 60 * 1000
+
+/** Default device credential lifetime: 90 days */
+export const DEFAULT_DEVICE_CREDENTIAL_LIFETIME = 90 * 24 * 60 * 60 * 1000
+
+/** Default maximum offline duration: 30 days */
+export const DEFAULT_MAX_OFFLINE_DURATION = 30 * 24 * 60 * 60 * 1000
+
+/** Default auto-lock timeout: 15 minutes */
+export const DEFAULT_AUTO_LOCK_TIMEOUT = 15 * 60 * 1000

package/src/vue/auth-context.ts

@@ -0,0 +1,10 @@
+import type { AuthClient, AuthState } from '../client/auth-client'
+
+export interface AuthContextValue {
+	client: AuthClient
+	state: AuthState
+	isLoading: boolean
+	session: import('../bindings/create-auth-session').AuthSession
+}
+
+export const authContextKey = Symbol('korajs-auth-context')

package/src/vue/auth-provider-types.ts

@@ -0,0 +1,5 @@
+/** Props for {@link AuthProvider}. */
+export interface AuthProviderProps {
+	client: import('../client/auth-client').AuthClient
+	fallback?: import('vue').VNode | string | null
+}

package/src/vue/auth-provider.ts

@@ -0,0 +1,76 @@
+import type { PropType, VNode } from 'vue'
+import { defineComponent, h, inject, onScopeDispose, provide, shallowRef } from 'vue'
+import { type AuthSessionSnapshot, createAuthSession } from '../bindings/create-auth-session'
+import type { AuthClient } from '../client/auth-client'
+import { type AuthContextValue, authContextKey } from './auth-context'
+
+export const AuthProvider = defineComponent({
+	name: 'AuthProvider',
+	props: {
+		client: {
+			type: Object as PropType<AuthClient>,
+			required: true,
+		},
+		fallback: {
+			type: [Object, String] as PropType<VNode | string | null>,
+			default: null,
+		},
+	},
+	setup(props, { slots }) {
+		const session = createAuthSession(props.client)
+		const snapshot = shallowRef<AuthSessionSnapshot>(session.getSnapshot())
+
+		const unsubscribe = session.subscribe(() => {
+			snapshot.value = session.getSnapshot()
+		})
+
+		onScopeDispose(() => {
+			unsubscribe()
+			session.destroy()
+		})
+
+		const contextValue: AuthContextValue = {
+			client: props.client,
+			get state() {
+				return snapshot.value.state
+			},
+			get isLoading() {
+				return snapshot.value.isLoading
+			},
+			session,
+		}
+
+		provide(authContextKey, contextValue)
+
+		return () => {
+			const current = snapshot.value
+
+			if (current.initError) {
+				return h(
+					'div',
+					{
+						style: { color: 'red', padding: '1rem', fontFamily: 'monospace' },
+						role: 'alert',
+					},
+					[h('strong', null, 'Kora Auth initialization error: '), current.initError.message],
+				)
+			}
+
+			if (current.isLoading && props.fallback !== null) {
+				return props.fallback
+			}
+
+			return slots.default?.()
+		}
+	},
+})
+
+export function useAuthContext(): AuthContextValue {
+	const context = inject<AuthContextValue | undefined>(authContextKey)
+	if (!context) {
+		throw new Error(
+			'useAuth must be used within <AuthProvider>. Wrap your app with <AuthProvider client={authClient}>.',
+		)
+	}
+	return context
+}