@korajs/auth 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @korajs/auth
+
+Offline-first authentication for Kora.js applications.
+
+## Overview
+
+`@korajs/auth` provides a complete authentication system designed for offline-first applications. It includes:
+
+- **Client-side auth management** — token storage, session restoration, sign-up/sign-in/sign-out
+- **React hooks** — `useAuth()`, `useCurrentUser()`, `useAuthStatus()` for reactive auth state
+- **Server-side auth routes** — email/password authentication with JWT tokens
+- **Device identity** — ECDSA P-256 key pairs for proof-of-possession
+- **Token management** — access/refresh token lifecycle with rotation
+
+## Installation
+
+```bash
+pnpm add @korajs/auth
+```
+
+## Quick Start
+
+### Client-side (React)
+
+```tsx
+import { AuthClient } from '@korajs/auth'
+import { AuthProvider, useAuth } from '@korajs/auth/react'
+
+const authClient = new AuthClient({ serverUrl: 'http://localhost:3001' })
+
+function App() {
+  return (
+    <AuthProvider client={authClient}>
+      <MyApp />
+    </AuthProvider>
+  )
+}
+
+function MyApp() {
+  const { user, isAuthenticated, isLoading, signIn, signOut, error } = useAuth()
+
+  if (isLoading) return <div>Loading...</div>
+
+  if (!isAuthenticated) {
+    return (
+      <button onClick={() => signIn({ email: 'user@example.com', password: 'password' })}>
+        Sign In
+      </button>
+    )
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user?.name ?? user?.email}</p>
+      <button onClick={() => signOut()}>Sign Out</button>
+    </div>
+  )
+}
+```
+
+### Server-side
+
+```typescript
+import { BuiltInAuthRoutes, InMemoryUserStore, TokenManager } from '@korajs/auth/server'
+
+const userStore = new InMemoryUserStore()
+const tokenManager = new TokenManager({ secret: process.env.AUTH_SECRET! })
+const authRoutes = new BuiltInAuthRoutes({ userStore, tokenManager })
+
+// Wire into your HTTP server:
+app.post('/auth/signup', async (req, res) => {
+  const result = await authRoutes.handleSignUp(req.body)
+  res.status(result.status).json(result.body)
+})
+
+app.post('/auth/signin', async (req, res) => {
+  const result = await authRoutes.handleSignIn(req.body)
+  res.status(result.status).json(result.body)
+})
+
+app.post('/auth/refresh', async (req, res) => {
+  const result = await authRoutes.handleRefresh(req.body)
+  res.status(result.status).json(result.body)
+})
+
+app.get('/auth/me', async (req, res) => {
+  const token = req.headers.authorization?.replace('Bearer ', '') ?? ''
+  const result = await authRoutes.handleGetMe(token)
+  res.status(result.status).json(result.body)
+})
+
+// Bridge to Kora sync server:
+const syncServer = new KoraSyncServer({
+  store,
+  auth: authRoutes.toSyncAuthProvider(),
+})
+```
+
+## Exports
+
+### `@korajs/auth` (client entry)
+
+| Export | Description |
+|--------|-------------|
+| `AuthClient` | Client-side auth manager |
+| `TokenStore` | Client-side token persistence |
+| `generateDeviceKeyPair` | ECDSA P-256 key pair generation |
+| `exportPublicKeyJwk` | Export public key as JWK |
+| `signChallenge` | Sign challenge with device key |
+| `verifyChallenge` | Verify challenge signature |
+| `computePublicKeyThumbprint` | RFC 7638 JWK thumbprint |
+
+### `@korajs/auth/react`
+
+| Export | Description |
+|--------|-------------|
+| `AuthProvider` | React context provider |
+| `useAuth` | Full auth hook (user, methods, error) |
+| `useCurrentUser` | Lightweight current user hook |
+| `useAuthStatus` | Auth status for route guards |
+
+### `@korajs/auth/server`
+
+| Export | Description |
+|--------|-------------|
+| `BuiltInAuthRoutes` | HTTP route handlers |
+| `TokenManager` | JWT issuing/validation |
+| `InMemoryUserStore` | Dev/test user store |
+| `BuiltInProvider` | Adapter wrapping routes |
+| `hashPassword` / `verifyPassword` | PBKDF2 password hashing |
+| `encodeJwt` / `verifyJwt` | Low-level JWT operations |
+
+## Security
+
+- Passwords hashed with PBKDF2-SHA512 (600,000 iterations, 32-byte salt)
+- JWT tokens signed with HMAC-SHA256
+- Constant-time signature comparison (prevents timing attacks)
+- Device keys use ECDSA P-256 with non-extractable private keys
+- Refresh token rotation on each use
+- Access tokens expire in 15 minutes (configurable)
+
+## Architecture
+
+```
+Client                                Server
+┌──────────────────┐                 ┌──────────────────┐
+│   AuthClient     │                 │ BuiltInAuthRoutes│
+│   ├─ TokenStore  │ ──── HTTP ────> │ ├─ UserStore     │
+│   └─ AuthState   │                 │ ├─ TokenManager  │
+│                  │                 │ └─ PasswordHash  │
+│   React Hooks    │                 │                  │
+│   ├─ useAuth     │                 │ SyncAuthProvider │
+│   ├─ useCurrentUser                │ └─ authenticate()│
+│   └─ useAuthStatus                 └──────────────────┘
+└──────────────────┘
+```

package/dist/auth-client-CrDNuh10.d.cts

@@ -0,0 +1,181 @@
+import { KoraError } from '@korajs/core';
+
+/**
+ * Thrown when an authentication operation fails.
+ * Includes a machine-readable code and optional context for debugging.
+ */
+declare class AuthError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Possible authentication states for the client.
+ * - 'loading': Initial state while restoring tokens from storage
+ * - 'authenticated': User is signed in with a valid session
+ * - 'unauthenticated': No valid session exists
+ */
+type AuthState = 'loading' | 'authenticated' | 'unauthenticated';
+/**
+ * Authenticated user information.
+ */
+interface AuthUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+    /** Display name (may be absent if user did not provide one) */
+    name: string | null;
+}
+/**
+ * Configuration for the AuthClient.
+ */
+interface AuthClientConfig {
+    /** Base URL of the auth server (e.g. 'http://localhost:3001') */
+    serverUrl: string;
+    /** Storage key prefix for tokens. Defaults to 'kora_auth' */
+    storageKey?: string;
+}
+/**
+ * Client-side authentication manager for Kora.js.
+ *
+ * Manages token storage, session restoration, sign-up, sign-in, sign-out,
+ * token refresh, and auth state change notifications. Framework-agnostic --
+ * works in any JavaScript environment with `fetch` and optionally `localStorage`.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthClient({ serverUrl: 'http://localhost:3001' })
+ * await auth.initialize()
+ *
+ * if (!auth.isAuthenticated) {
+ *   await auth.signIn({ email: 'user@example.com', password: 'secret' })
+ * }
+ *
+ * const unsub = auth.onAuthChange((state) => {
+ *   console.log('Auth state:', state)
+ * })
+ * ```
+ */
+declare class AuthClient {
+    private readonly serverUrl;
+    private readonly storage;
+    private readonly listeners;
+    private _state;
+    private _user;
+    private _refreshPromise;
+    /**
+     * Creates a new AuthClient.
+     *
+     * @param config - Auth client configuration
+     */
+    constructor(config: AuthClientConfig);
+    /** Current authentication state. */
+    get state(): AuthState;
+    /** Current authenticated user, or null if not signed in. */
+    get currentUser(): AuthUser | null;
+    /** Whether the user is currently authenticated. */
+    get isAuthenticated(): boolean;
+    /**
+     * Initialize the auth client by restoring a session from stored tokens.
+     *
+     * Loads tokens from storage, validates the access token, and attempts a
+     * refresh if the access token is expired but a refresh token is available.
+     * Safe to call multiple times -- subsequent calls are no-ops once initialized.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a new user account.
+     *
+     * @param params - Sign-up credentials
+     * @returns The newly created AuthUser
+     * @throws {AuthError} If the request fails or the server returns an error
+     */
+    signUp(params: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<AuthUser>;
+    /**
+     * Sign in with email and password.
+     *
+     * @param params - Sign-in credentials
+     * @returns The authenticated AuthUser
+     * @throws {AuthError} If the credentials are invalid or the request fails
+     */
+    signIn(params: {
+        email: string;
+        password: string;
+    }): Promise<AuthUser>;
+    /**
+     * Sign out the current user.
+     *
+     * Clears local tokens and state. Does not make a network request to the
+     * server -- tokens are simply discarded locally.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get a valid access token, automatically refreshing if expired.
+     *
+     * @returns A valid access token string, or null if the user is not
+     *          authenticated and refresh is not possible
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get a valid token for the sync engine handshake.
+     * Alias for {@link getAccessToken}.
+     *
+     * @returns A valid access token string, or null if unavailable
+     */
+    getSyncToken(): Promise<string | null>;
+    /**
+     * Subscribe to authentication state changes.
+     *
+     * The callback is invoked whenever the auth state transitions (e.g., from
+     * 'unauthenticated' to 'authenticated' on sign-in).
+     *
+     * @param callback - Function called with the new AuthState on each change
+     * @returns An unsubscribe function that removes the listener
+     *
+     * @example
+     * ```typescript
+     * const unsub = auth.onAuthChange((state) => {
+     *   console.log('Auth state changed to:', state)
+     * })
+     * // Later: unsub()
+     * ```
+     */
+    onAuthChange(callback: (state: AuthState) => void): () => void;
+    /**
+     * Update internal state and notify all listeners.
+     */
+    private setState;
+    /**
+     * Restore a session from a valid access token by fetching the user profile.
+     * Falls back to extracting the user ID from the token payload if the
+     * /auth/me request fails (offline scenario).
+     */
+    private restoreSession;
+    /**
+     * Fetch the current user profile from the server.
+     */
+    private fetchUserProfile;
+    /**
+     * Refresh the access token using a refresh token.
+     * De-duplicates concurrent refresh calls so only one network request is made.
+     */
+    private refreshAccessToken;
+    /**
+     * Execute the token refresh network request.
+     */
+    private performRefresh;
+    /**
+     * Make an HTTP request to the auth server.
+     *
+     * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
+     * @param options - Request options
+     * @returns Parsed JSON response body
+     * @throws {AuthError} On network failure or non-2xx response
+     */
+    private request;
+}
+
+export { AuthClient as A, type AuthClientConfig as a, AuthError as b, type AuthState as c, type AuthUser as d };

package/dist/auth-client-CrDNuh10.d.ts

@@ -0,0 +1,181 @@
+import { KoraError } from '@korajs/core';
+
+/**
+ * Thrown when an authentication operation fails.
+ * Includes a machine-readable code and optional context for debugging.
+ */
+declare class AuthError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Possible authentication states for the client.
+ * - 'loading': Initial state while restoring tokens from storage
+ * - 'authenticated': User is signed in with a valid session
+ * - 'unauthenticated': No valid session exists
+ */
+type AuthState = 'loading' | 'authenticated' | 'unauthenticated';
+/**
+ * Authenticated user information.
+ */
+interface AuthUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+    /** Display name (may be absent if user did not provide one) */
+    name: string | null;
+}
+/**
+ * Configuration for the AuthClient.
+ */
+interface AuthClientConfig {
+    /** Base URL of the auth server (e.g. 'http://localhost:3001') */
+    serverUrl: string;
+    /** Storage key prefix for tokens. Defaults to 'kora_auth' */
+    storageKey?: string;
+}
+/**
+ * Client-side authentication manager for Kora.js.
+ *
+ * Manages token storage, session restoration, sign-up, sign-in, sign-out,
+ * token refresh, and auth state change notifications. Framework-agnostic --
+ * works in any JavaScript environment with `fetch` and optionally `localStorage`.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthClient({ serverUrl: 'http://localhost:3001' })
+ * await auth.initialize()
+ *
+ * if (!auth.isAuthenticated) {
+ *   await auth.signIn({ email: 'user@example.com', password: 'secret' })
+ * }
+ *
+ * const unsub = auth.onAuthChange((state) => {
+ *   console.log('Auth state:', state)
+ * })
+ * ```
+ */
+declare class AuthClient {
+    private readonly serverUrl;
+    private readonly storage;
+    private readonly listeners;
+    private _state;
+    private _user;
+    private _refreshPromise;
+    /**
+     * Creates a new AuthClient.
+     *
+     * @param config - Auth client configuration
+     */
+    constructor(config: AuthClientConfig);
+    /** Current authentication state. */
+    get state(): AuthState;
+    /** Current authenticated user, or null if not signed in. */
+    get currentUser(): AuthUser | null;
+    /** Whether the user is currently authenticated. */
+    get isAuthenticated(): boolean;
+    /**
+     * Initialize the auth client by restoring a session from stored tokens.
+     *
+     * Loads tokens from storage, validates the access token, and attempts a
+     * refresh if the access token is expired but a refresh token is available.
+     * Safe to call multiple times -- subsequent calls are no-ops once initialized.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a new user account.
+     *
+     * @param params - Sign-up credentials
+     * @returns The newly created AuthUser
+     * @throws {AuthError} If the request fails or the server returns an error
+     */
+    signUp(params: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<AuthUser>;
+    /**
+     * Sign in with email and password.
+     *
+     * @param params - Sign-in credentials
+     * @returns The authenticated AuthUser
+     * @throws {AuthError} If the credentials are invalid or the request fails
+     */
+    signIn(params: {
+        email: string;
+        password: string;
+    }): Promise<AuthUser>;
+    /**
+     * Sign out the current user.
+     *
+     * Clears local tokens and state. Does not make a network request to the
+     * server -- tokens are simply discarded locally.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get a valid access token, automatically refreshing if expired.
+     *
+     * @returns A valid access token string, or null if the user is not
+     *          authenticated and refresh is not possible
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get a valid token for the sync engine handshake.
+     * Alias for {@link getAccessToken}.
+     *
+     * @returns A valid access token string, or null if unavailable
+     */
+    getSyncToken(): Promise<string | null>;
+    /**
+     * Subscribe to authentication state changes.
+     *
+     * The callback is invoked whenever the auth state transitions (e.g., from
+     * 'unauthenticated' to 'authenticated' on sign-in).
+     *
+     * @param callback - Function called with the new AuthState on each change
+     * @returns An unsubscribe function that removes the listener
+     *
+     * @example
+     * ```typescript
+     * const unsub = auth.onAuthChange((state) => {
+     *   console.log('Auth state changed to:', state)
+     * })
+     * // Later: unsub()
+     * ```
+     */
+    onAuthChange(callback: (state: AuthState) => void): () => void;
+    /**
+     * Update internal state and notify all listeners.
+     */
+    private setState;
+    /**
+     * Restore a session from a valid access token by fetching the user profile.
+     * Falls back to extracting the user ID from the token payload if the
+     * /auth/me request fails (offline scenario).
+     */
+    private restoreSession;
+    /**
+     * Fetch the current user profile from the server.
+     */
+    private fetchUserProfile;
+    /**
+     * Refresh the access token using a refresh token.
+     * De-duplicates concurrent refresh calls so only one network request is made.
+     */
+    private refreshAccessToken;
+    /**
+     * Execute the token refresh network request.
+     */
+    private performRefresh;
+    /**
+     * Make an HTTP request to the auth server.
+     *
+     * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
+     * @param options - Request options
+     * @returns Parsed JSON response body
+     * @throws {AuthError} On network failure or non-2xx response
+     */
+    private request;
+}
+
+export { AuthClient as A, type AuthClientConfig as a, AuthError as b, type AuthState as c, type AuthUser as d };

package/dist/chunk-L554ZDPY.js

@@ -0,0 +1,174 @@
+// src/device/device-identity.ts
+import { KoraError } from "@korajs/core";
+var CryptoUnavailableError = class extends KoraError {
+  constructor() {
+    super(
+      "Web Crypto API (crypto.subtle) is not available in this environment. Device identity requires crypto.subtle, which is available in modern browsers and Node.js 20+. If running in SSR, ensure your runtime provides the Web Crypto API.",
+      "CRYPTO_UNAVAILABLE"
+    );
+    this.name = "CryptoUnavailableError";
+  }
+};
+var DeviceIdentityError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "DEVICE_IDENTITY_ERROR", context);
+    this.name = "DeviceIdentityError";
+  }
+};
+function toBase64Url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(str) {
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const paddingNeeded = (4 - base64.length % 4) % 4;
+  base64 += "=".repeat(paddingNeeded);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function assertCryptoAvailable() {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new CryptoUnavailableError();
+  }
+}
+var ECDSA_ALGORITHM = {
+  name: "ECDSA",
+  namedCurve: "P-256"
+};
+var ECDSA_SIGN_ALGORITHM = {
+  name: "ECDSA",
+  hash: { name: "SHA-256" }
+};
+async function generateDeviceKeyPair() {
+  assertCryptoAvailable();
+  try {
+    const keyPair = await globalThis.crypto.subtle.generateKey(
+      ECDSA_ALGORITHM,
+      // extractable: false makes the private key non-extractable.
+      // The public key is always extractable regardless of this flag.
+      false,
+      ["sign", "verify"]
+    );
+    return keyPair;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to generate ECDSA P-256 device key pair. Ensure the runtime supports the ECDSA algorithm with the P-256 curve.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function exportPublicKeyJwk(keyPair) {
+  assertCryptoAvailable();
+  try {
+    const jwk = await globalThis.crypto.subtle.exportKey("jwk", keyPair.publicKey);
+    return jwk;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to export public key as JWK. The key pair may be invalid or the public key may not support JWK export.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function signChallenge(privateKey, challenge) {
+  assertCryptoAvailable();
+  try {
+    const encoded = new TextEncoder().encode(challenge);
+    const signatureBuffer = await globalThis.crypto.subtle.sign(
+      ECDSA_SIGN_ALGORITHM,
+      privateKey,
+      encoded
+    );
+    return toBase64Url(signatureBuffer);
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      'Failed to sign challenge. Ensure the key is a valid ECDSA P-256 private key with "sign" usage.',
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function verifyChallenge(publicKeyJwk, challenge, signature) {
+  assertCryptoAvailable();
+  try {
+    const publicKey = await globalThis.crypto.subtle.importKey(
+      "jwk",
+      publicKeyJwk,
+      ECDSA_ALGORITHM,
+      true,
+      ["verify"]
+    );
+    const encoded = new TextEncoder().encode(challenge);
+    const signatureBytes = fromBase64Url(signature);
+    const isValid = await globalThis.crypto.subtle.verify(
+      ECDSA_SIGN_ALGORITHM,
+      publicKey,
+      signatureBytes,
+      encoded
+    );
+    return isValid;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to verify challenge signature. The public key JWK or signature format may be invalid.",
+      {
+        cause: cause instanceof Error ? cause.message : String(cause),
+        publicKeyKty: publicKeyJwk.kty,
+        publicKeyCrv: publicKeyJwk.crv
+      }
+    );
+  }
+}
+async function computePublicKeyThumbprint(publicKeyJwk) {
+  assertCryptoAvailable();
+  if (publicKeyJwk.kty !== "EC") {
+    throw new DeviceIdentityError(
+      `Expected JWK key type "EC" but received "${publicKeyJwk.kty ?? "undefined"}". Only ECDSA public keys are supported for device identity.`,
+      { kty: publicKeyJwk.kty }
+    );
+  }
+  if (!publicKeyJwk.crv || !publicKeyJwk.x || !publicKeyJwk.y) {
+    throw new DeviceIdentityError(
+      'JWK is missing required EC fields. An EC public key JWK must include "crv", "x", and "y" members.',
+      {
+        hasCrv: Boolean(publicKeyJwk.crv),
+        hasX: Boolean(publicKeyJwk.x),
+        hasY: Boolean(publicKeyJwk.y)
+      }
+    );
+  }
+  const canonicalJson = JSON.stringify({
+    crv: publicKeyJwk.crv,
+    kty: publicKeyJwk.kty,
+    x: publicKeyJwk.x,
+    y: publicKeyJwk.y
+  });
+  try {
+    const encoded = new TextEncoder().encode(canonicalJson);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+    return toBase64Url(hashBuffer);
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to compute SHA-256 thumbprint of the public key JWK.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+
+export {
+  CryptoUnavailableError,
+  DeviceIdentityError,
+  toBase64Url,
+  fromBase64Url,
+  generateDeviceKeyPair,
+  exportPublicKeyJwk,
+  signChallenge,
+  verifyChallenge,
+  computePublicKeyThumbprint
+};
+//# sourceMappingURL=chunk-L554ZDPY.js.map