@brika/auth 0.1.1

package/src/__tests__/verifyToken.test.ts

@@ -0,0 +1,219 @@
+/**
+ * @brika/auth - verifyToken Middleware Tests
+ *
+ * Tests for token extraction (cookie + Authorization header),
+ * IP forwarding, and session attachment to context.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'bun:test';
+import { container } from '@brika/di';
+import { initAuthConfig } from '../config';
+import { verifyToken } from '../middleware/verifyToken';
+import { SessionService } from '../services/SessionService';
+import type { Session } from '../types';
+import { Role, Scope } from '../types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function mockContext(
+  url: string,
+  options?: {
+    cookie?: string;
+    auth?: string;
+    ip?: string;
+    realIp?: string;
+  }
+) {
+  const next = vi.fn().mockResolvedValue(undefined);
+  const ctx = {
+    req: {
+      url,
+      header: vi.fn((name: string) => {
+        if (name === 'Cookie') {
+          return options?.cookie;
+        }
+        if (name === 'Authorization') {
+          return options?.auth;
+        }
+        if (name === 'x-forwarded-for') {
+          return options?.ip;
+        }
+        if (name === 'x-real-ip') {
+          return options?.realIp;
+        }
+        return undefined;
+      }),
+    },
+    get: vi.fn(),
+    set: vi.fn(),
+  };
+  return {
+    ctx,
+    next,
+  };
+}
+
+const fakeSession: Session = {
+  id: 'sess-abc',
+  userId: 'user-1',
+  userEmail: 'user@test.com',
+  userName: 'Test User',
+  userRole: Role.USER,
+  scopes: [Scope.WORKFLOW_READ],
+};
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const mockSessionService = {
+  validateSession: vi.fn(),
+};
+
+beforeEach(() => {
+  container.clearInstances();
+  container.register(SessionService, {
+    useValue: mockSessionService as never,
+  });
+  mockSessionService.validateSession.mockReset();
+  initAuthConfig(); // ensures cookieName defaults to 'brika_session'
+});
+
+afterEach(() => {
+  container.clearInstances();
+});
+
+// ---------------------------------------------------------------------------
+// verifyToken
+// ---------------------------------------------------------------------------
+
+describe('verifyToken', () => {
+  it('sets null session and calls next when no cookie or auth header', async () => {
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test');
+
+    await middleware(ctx as never, next);
+
+    expect(ctx.set).toHaveBeenCalledWith('session', null);
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(mockSessionService.validateSession).not.toHaveBeenCalled();
+  });
+
+  it('extracts token from cookie and calls validateSession', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      cookie: 'brika_session=my-token-value',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).toHaveBeenCalledWith('my-token-value', undefined);
+    expect(ctx.set).toHaveBeenCalledWith('session', fakeSession);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to Authorization Bearer header when no cookie', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      auth: 'Bearer bearer-token-value',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).toHaveBeenCalledWith(
+      'bearer-token-value',
+      undefined
+    );
+    expect(ctx.set).toHaveBeenCalledWith('session', fakeSession);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes x-forwarded-for IP to validateSession', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      cookie: 'brika_session=token-xyz',
+      ip: '203.0.113.42',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).toHaveBeenCalledWith('token-xyz', '203.0.113.42');
+  });
+
+  it('falls back to x-real-ip when x-forwarded-for is absent', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      cookie: 'brika_session=token-xyz',
+      realIp: '198.51.100.7',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).toHaveBeenCalledWith('token-xyz', '198.51.100.7');
+  });
+
+  it('sets session from validateSession return value on context', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      cookie: 'brika_session=valid-token',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(ctx.set).toHaveBeenCalledWith('session', fakeSession);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets null session when validateSession returns null (expired/revoked)', async () => {
+    mockSessionService.validateSession.mockReturnValue(null);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      cookie: 'brika_session=expired-token',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(ctx.set).toHaveBeenCalledWith('session', null);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getCookieValue (via cookie parsing behaviour of the middleware)
+// ---------------------------------------------------------------------------
+
+describe('verifyToken cookie parsing', () => {
+  it('handles multiple cookies and extracts the correct one', async () => {
+    mockSessionService.validateSession.mockReturnValue(fakeSession);
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      // brika_session is the second cookie in the header string
+      cookie: 'other_cookie=irrelevant; brika_session=correct-token; another=value',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).toHaveBeenCalledWith('correct-token', undefined);
+  });
+
+  it('sets null session when the cookie name is not present in the header', async () => {
+    const middleware = verifyToken();
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', {
+      // Cookie header exists but does not contain brika_session
+      cookie: 'some_other_cookie=value',
+    });
+
+    await middleware(ctx as never, next);
+
+    expect(mockSessionService.validateSession).not.toHaveBeenCalled();
+    expect(ctx.set).toHaveBeenCalledWith('session', null);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/client/AuthClient.ts

@@ -0,0 +1,312 @@
+/**
+ * Auth Client — Cookie-based session authentication
+ *
+ * The server sets an HttpOnly cookie on login.
+ * All requests include `credentials: 'include'` so the browser sends it automatically.
+ *
+ * Usage:
+ *   const auth = new AuthClient()
+ *   const session = await auth.login(email, password)
+ *   await auth.logout()
+ */
+
+export class AuthError extends Error {
+  constructor(
+    message: string,
+    readonly status: number
+  ) {
+    super(message);
+  }
+}
+
+export interface AuthClientConfig {
+  apiUrl?: string;
+}
+
+export interface SessionInfo {
+  id: string;
+  ip: string | null;
+  userAgent: string | null;
+  createdAt: number;
+  lastSeenAt: number;
+  current: boolean;
+}
+
+export interface LoginResponse {
+  user: Session['user'];
+}
+
+export interface Session {
+  user: {
+    id: string;
+    email: string;
+    name: string;
+    role: string;
+    avatarHash: string | null;
+    createdAt: string;
+    updatedAt: string;
+  };
+  scopes?: string[];
+}
+
+export class AuthClient {
+  private readonly apiUrl: string;
+
+  constructor(config: AuthClientConfig = {}) {
+    this.apiUrl =
+      config.apiUrl ||
+      (globalThis.window === undefined
+        ? 'http://localhost:3001'
+        : globalThis.window.location.origin);
+
+    // Clean up legacy localStorage keys from pre-cookie auth
+    if (globalThis.window !== undefined) {
+      localStorage.removeItem('brika_token');
+      localStorage.removeItem('brika_session');
+    }
+  }
+
+  /**
+   * Login with email and password.
+   * Server sets HttpOnly cookie — no token stored client-side.
+   * After the cookie is set, fetches the full session (with scopes).
+   */
+  async login(email: string, password: string): Promise<Session> {
+    await this.request('/api/auth/login', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        email,
+        password,
+      }),
+    });
+
+    // Cookie is now set — fetch full session including scopes
+    const session = await this.getSession();
+    if (!session) {
+      throw new Error('Login failed');
+    }
+    return session;
+  }
+
+  /**
+   * Logout — server revokes session and clears cookie.
+   */
+  async logout(): Promise<void> {
+    try {
+      await fetch(`${this.apiUrl}/api/auth/logout`, {
+        method: 'POST',
+        credentials: 'include',
+      });
+    } catch {
+      // Silent fail — cookie will expire anyway
+    }
+  }
+
+  /**
+   * Get current session from server (validates cookie).
+   */
+  async getSession(): Promise<Session | null> {
+    try {
+      const data = await this.request<{
+        user: Session['user'];
+        scopes: string[];
+      }>('/api/auth/session');
+      return {
+        user: data.user,
+        scopes: data.scopes,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Update own profile (name).
+   */
+  async updateProfile(updates: { name?: string }): Promise<Session> {
+    return await this.request<Session>('/api/auth/profile', {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(updates),
+    });
+  }
+
+  /**
+   * Upload avatar image. Processed to webp on server.
+   * Returns the new avatar content hash for cache busting.
+   */
+  async uploadAvatar(file: Blob): Promise<string> {
+    const data = await this.request<{
+      ok: boolean;
+      avatarHash: string;
+    }>('/api/auth/profile/avatar', {
+      method: 'PUT',
+      body: file,
+    });
+    return data.avatarHash;
+  }
+
+  /**
+   * Remove avatar.
+   */
+  async removeAvatar(): Promise<void> {
+    await this.request('/api/auth/profile/avatar', {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * Get avatar URL for a user.
+   * Accepts a user-like object `{ id, avatarHash }` — the hash makes the URL
+   * content-addressed so the browser fetches a new image when the avatar changes.
+   */
+  avatarUrl(
+    user: {
+      id: string;
+      avatarHash?: string | null;
+    },
+    options?: {
+      size?: number;
+      dpr?: number;
+    }
+  ): string {
+    const params = new URLSearchParams();
+
+    const dpr = options?.dpr ?? globalThis.devicePixelRatio ?? 1;
+    const size = options?.size ? Math.round(options.size * dpr) : undefined;
+    if (size) {
+      params.set('s', String(size));
+    }
+
+    if (user.avatarHash) {
+      params.set('v', user.avatarHash);
+    }
+
+    const qs = params.toString();
+    const suffix = qs ? `?${qs}` : '';
+    return `${this.apiUrl}/api/auth/avatar/${user.id}${suffix}`;
+  }
+
+  /**
+   * List all active sessions for the current user.
+   */
+  async listSessions(): Promise<SessionInfo[]> {
+    const data = await this.request<{
+      sessions: SessionInfo[];
+    }>('/api/auth/sessions');
+    return data.sessions;
+  }
+
+  /**
+   * Revoke a specific session by ID.
+   */
+  async revokeSession(sessionId: string): Promise<void> {
+    await this.request<{
+      ok: boolean;
+    }>(`/api/auth/sessions/${sessionId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * Change own password. Requires current password for verification.
+   */
+  async changePassword(currentPassword: string, newPassword: string): Promise<void> {
+    await this.request('/api/auth/profile/password', {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        currentPassword,
+        newPassword,
+      }),
+    });
+  }
+
+  /**
+   * Revoke all sessions for the current user (signs out everywhere).
+   */
+  async revokeAllSessions(): Promise<void> {
+    await this.request<{
+      ok: boolean;
+    }>('/api/auth/sessions', {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * Check if initial setup is needed (no admin or setup not completed).
+   * Uses the hub-level endpoint that combines auth + hub state checks.
+   */
+  async checkSetupStatus(): Promise<{ needsSetup: boolean }> {
+    try {
+      return await this.request<{ needsSetup: boolean }>('/api/setup/status');
+    } catch {
+      return { needsSetup: false };
+    }
+  }
+
+  /**
+   * Mark the onboarding wizard as fully completed.
+   * Called at the final step after all setup screens are done.
+   */
+  async completeSetup(): Promise<void> {
+    await this.request('/api/setup/complete', { method: 'POST' });
+  }
+
+  /**
+   * Create the first admin user during initial setup.
+   * Server sets session cookie automatically.
+   */
+  async setup(data: { email: string; name: string; password: string }): Promise<Session> {
+    await this.request('/api/auth/setup', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+
+    const session = await this.getSession();
+    if (!session) {
+      throw new Error('Setup failed');
+    }
+    return session;
+  }
+
+  /**
+   * Make authenticated request (cookie sent automatically).
+   */
+  async request<T>(url: string, options: RequestInit = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}${url}`, {
+      ...options,
+      credentials: 'include',
+    });
+
+    if (!response.ok) {
+      const body = await response.json().catch(() => null);
+      throw new AuthError(
+        body?.error ?? (response.status === 401 ? 'Unauthorized' : 'Request failed'),
+        response.status
+      );
+    }
+
+    return await response.json();
+  }
+}
+
+/** Singleton instance */
+let authClient: AuthClient | null = null;
+
+export function getAuthClient(config?: AuthClientConfig): AuthClient {
+  authClient ??= new AuthClient(config);
+  return authClient;
+}
+
+export function createAuthClient(config?: AuthClientConfig): AuthClient {
+  return new AuthClient(config);
+}

package/src/client/http-client.ts

@@ -0,0 +1,84 @@
+/**
+ * @brika/auth/client - HTTP Client
+ *
+ * Simple HTTP client for making auth API calls.
+ * Uses credentials: 'include' for cookie-based auth.
+ */
+
+import type { LoginRequest } from '../types';
+import type { LoginResponse } from './AuthClient';
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  fetch?: typeof fetch;
+}
+
+/**
+ * HTTP client for auth API calls
+ */
+export class AuthHttpClient {
+  private readonly baseUrl: string;
+  private readonly fetch: typeof fetch;
+
+  constructor(options: HttpClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, '');
+    this.fetch = options.fetch || globalThis.fetch;
+  }
+
+  /**
+   * Login with email and password
+   */
+  async login(credentials: LoginRequest): Promise<LoginResponse> {
+    const response = await this.fetch(`${this.baseUrl}/api/auth/login`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(credentials),
+      credentials: 'include',
+    });
+
+    if (!response.ok) {
+      throw new Error('Login failed');
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Logout — server clears the session cookie
+   */
+  async logout(): Promise<void> {
+    await this.fetch(`${this.baseUrl}/api/auth/logout`, {
+      method: 'POST',
+      credentials: 'include',
+    });
+  }
+
+  /**
+   * Verify current session (cookie sent automatically)
+   */
+  async verify(): Promise<boolean> {
+    const response = await this.fetch(`${this.baseUrl}/api/auth/session`, {
+      credentials: 'include',
+    });
+
+    return response.ok;
+  }
+
+  /**
+   * Make authenticated request (cookie sent automatically)
+   */
+  async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const response = await this.fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      credentials: 'include',
+    });
+
+    if (!response.ok) {
+      throw new Error(`Request failed: ${response.statusText}`);
+    }
+
+    return response.json();
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @brika/auth/client
+ *
+ * Client-side authentication module.
+ * Use this to make HTTP calls to your auth API.
+ *
+ * @example
+ * ```ts
+ * import { AuthHttpClient } from '@brika/auth/client';
+ *
+ * const client = new AuthHttpClient({ baseUrl: 'http://localhost:3001' });
+ * const { user } = await client.login({
+ *   email: 'user@example.com',
+ *   password: 'password123',
+ * });
+ * ```
+ */
+
+export { AuthHttpClient, type HttpClientOptions } from './http-client';

package/src/config.ts

@@ -0,0 +1,82 @@
+/**
+ * @brika/auth - Configuration
+ *
+ * Runtime-configurable auth settings. The hub passes config via the
+ * auth plugin; defaults apply when no config is provided.
+ *
+ * @example
+ * auth({ dataDir, server, config: { session: { ttl: 86400 } } })
+ */
+
+export interface AuthConfig {
+  session?: {
+    /** Session TTL in seconds (default: 604800 = 7 days) */
+    ttl?: number;
+    /** Cookie name (default: 'brika_session') */
+    cookieName?: string;
+    /** Max active sessions per user (default: 10). Oldest sessions are revoked when exceeded. */
+    maxPerUser?: number;
+  };
+  password?: {
+    /** Minimum length (default: 8) */
+    minLength?: number;
+    /** Require uppercase letter (default: true) */
+    requireUppercase?: boolean;
+    /** Require digit (default: true) */
+    requireNumbers?: boolean;
+    /** Require special character (default: true) */
+    requireSpecial?: boolean;
+  };
+}
+
+export interface ResolvedAuthConfig {
+  session: {
+    ttl: number;
+    cookieName: string;
+    maxPerUser: number;
+  };
+  password: {
+    minLength: number;
+    requireUppercase: boolean;
+    requireNumbers: boolean;
+    requireSpecial: boolean;
+    specialChars: RegExp;
+  };
+}
+
+export const AUTH_DEFAULTS: ResolvedAuthConfig = {
+  session: {
+    ttl: 604800, // 7 days
+    cookieName: 'brika_session',
+    maxPerUser: 10,
+  },
+  password: {
+    minLength: 8,
+    requireUppercase: true,
+    requireNumbers: true,
+    requireSpecial: true,
+    specialChars: /[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/,
+  },
+};
+
+let _config: ResolvedAuthConfig = AUTH_DEFAULTS;
+
+/** Initialize auth config. Call once during bootstrap. */
+export function initAuthConfig(config?: AuthConfig): ResolvedAuthConfig {
+  _config = {
+    session: {
+      ...AUTH_DEFAULTS.session,
+      ...config?.session,
+    },
+    password: {
+      ...AUTH_DEFAULTS.password,
+      ...config?.password,
+    },
+  };
+  return _config;
+}
+
+/** Get the resolved auth config. */
+export function getAuthConfig(): ResolvedAuthConfig {
+  return _config;
+}