@brika/auth 0.1.1

package/src/__tests__/disabledScopes.test.ts

@@ -0,0 +1,101 @@
+/**
+ * @brika/auth - Per-user scopes (allow-list) tests
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { ROLE_SCOPES } from '../constants';
+import { SessionService } from '../services/SessionService';
+import { UserService } from '../services/UserService';
+import { openAuthDatabase } from '../setup';
+import { Role, Scope } from '../types';
+
+describe('Per-user scopes (allow-list)', () => {
+  let userService: UserService;
+  let sessionService: SessionService;
+
+  beforeEach(() => {
+    const db = openAuthDatabase(':memory:');
+    userService = new UserService(db);
+    sessionService = new SessionService(db, 3600);
+  });
+
+  it('should grant role default scopes to new users', () => {
+    const user = userService.createUser('test@test.com', 'Test', Role.USER);
+    expect(user.scopes).toEqual(ROLE_SCOPES[Role.USER]);
+
+    const token = sessionService.createSession(user.id);
+    const session = sessionService.validateSession(token);
+    expect(session).not.toBeNull();
+    expect(session?.scopes).toEqual(ROLE_SCOPES[Role.USER]);
+  });
+
+  it('should use only explicitly granted scopes in session', () => {
+    const user = userService.createUser('test@test.com', 'Test', Role.USER);
+    userService.updateUser(user.id, {
+      scopes: [Scope.WORKFLOW_READ, Scope.WORKFLOW_EXECUTE],
+    });
+
+    const token = sessionService.createSession(user.id);
+    const session = sessionService.validateSession(token);
+
+    expect(session).not.toBeNull();
+    expect(session?.scopes).toContain(Scope.WORKFLOW_READ);
+    expect(session?.scopes).toContain(Scope.WORKFLOW_EXECUTE);
+    expect(session?.scopes).not.toContain(Scope.WORKFLOW_WRITE);
+    expect(session?.scopes).not.toContain(Scope.BOARD_WRITE);
+  });
+
+  it('should always grant admin scopes regardless of stored scopes', () => {
+    const user = userService.createUser('admin@test.com', 'Admin', Role.ADMIN);
+    // Even if scopes are manually narrowed, admin always gets ADMIN_ALL
+    userService.updateUser(user.id, {
+      scopes: [Scope.WORKFLOW_READ],
+    });
+
+    const token = sessionService.createSession(user.id);
+    const session = sessionService.validateSession(token);
+
+    expect(session).not.toBeNull();
+    expect(session?.scopes).toContain(Scope.ADMIN_ALL);
+  });
+
+  it('should persist and retrieve scopes on User object', () => {
+    const user = userService.createUser('test@test.com', 'Test', Role.USER);
+    const updated = userService.updateUser(user.id, {
+      scopes: [Scope.PLUGIN_READ, Scope.BOARD_READ],
+    });
+
+    expect(updated.scopes).toEqual([Scope.PLUGIN_READ, Scope.BOARD_READ]);
+  });
+
+  it('should handle empty scopes (no permissions)', () => {
+    const user = userService.createUser('test@test.com', 'Test', Role.USER);
+    const updated = userService.updateUser(user.id, {
+      scopes: [],
+    });
+
+    expect(updated.scopes).toEqual([]);
+
+    const token = sessionService.createSession(user.id);
+    const session = sessionService.validateSession(token);
+    expect(session?.scopes).toEqual([]);
+  });
+
+  it('should grant role-appropriate defaults for each role', () => {
+    const guest = userService.createUser('guest@test.com', 'Guest', Role.GUEST);
+    expect(guest.scopes).toEqual(ROLE_SCOPES[Role.GUEST]);
+
+    const admin = userService.createUser('admin@test.com', 'Admin', Role.ADMIN);
+    expect(admin.scopes).toEqual(ROLE_SCOPES[Role.ADMIN]);
+  });
+
+  it('should drop invalid scope strings when reading from DB', () => {
+    const user = userService.createUser('test@test.com', 'Test', Role.USER);
+    userService.updateUser(user.id, {
+      scopes: [Scope.WORKFLOW_READ, 'not:a:scope' as Scope],
+    });
+
+    const fetched = userService.getUser(user.id);
+    expect(fetched?.scopes).toEqual([Scope.WORKFLOW_READ]);
+  });
+});

package/src/__tests__/middleware.test.ts

@@ -0,0 +1,190 @@
+/**
+ * @brika/auth - Middleware Tests
+ *
+ * Tests for requireAuth and requireScope middleware.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'bun:test';
+import { container } from '@brika/di';
+import { requireAuth } from '../middleware/requireAuth';
+import { requireScope } from '../middleware/requireScope';
+import { ScopeService } from '../services/ScopeService';
+import type { Session } from '../types';
+import { Role, Scope } from '../types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const adminSession: Session = {
+  id: 'sess-admin',
+  userId: 'user-admin',
+  userEmail: 'admin@test.com',
+  userName: 'Admin',
+  userRole: Role.ADMIN,
+  scopes: [Scope.ADMIN_ALL],
+};
+
+const userSession: Session = {
+  id: 'sess-user',
+  userId: 'user-1',
+  userEmail: 'user@test.com',
+  userName: 'User',
+  userRole: Role.USER,
+  scopes: [Scope.WORKFLOW_READ, Scope.WORKFLOW_WRITE, Scope.BOARD_READ],
+};
+
+function mockContext(url: string, session: Session | null = null) {
+  const next = vi.fn().mockResolvedValue(undefined);
+  const ctx = {
+    req: {
+      url,
+      header: vi.fn().mockReturnValue(undefined),
+    },
+    get: vi.fn((key: string) => {
+      if (key === 'session') {
+        return session;
+      }
+      return undefined;
+    }),
+    set: vi.fn(),
+    json: vi.fn(
+      (body: Record<string, unknown>, status?: number) =>
+        new Response(JSON.stringify(body), {
+          status: status ?? 200,
+        })
+    ),
+  };
+  return {
+    ctx,
+    next,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// requireAuth
+// ---------------------------------------------------------------------------
+
+describe('requireAuth', () => {
+  const middleware = requireAuth();
+
+  it('should call next when session exists', async () => {
+    const { ctx, next } = mockContext('http://localhost:3001/api/test', userSession);
+    await middleware(ctx as never, next);
+    expect(next).toHaveBeenCalled();
+    expect(ctx.json).not.toHaveBeenCalled();
+  });
+
+  it('should return 401 when no session', async () => {
+    const { ctx, next } = mockContext('http://localhost:3001/api/test');
+    await middleware(ctx as never, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(ctx.json).toHaveBeenCalledWith(
+      {
+        error: 'Unauthorized',
+      },
+      401
+    );
+  });
+
+  it('should call next for admin session', async () => {
+    const { ctx, next } = mockContext('http://localhost:3001/api/admin', adminSession);
+    await middleware(ctx as never, next);
+    expect(next).toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// requireScope
+// ---------------------------------------------------------------------------
+
+describe('requireScope', () => {
+  beforeEach(() => {
+    container.clearInstances();
+    // ScopeService has no dependencies — register it directly
+    container.register(ScopeService, {
+      useClass: ScopeService,
+    });
+  });
+
+  afterEach(() => {
+    container.clearInstances();
+  });
+
+  it('should call next when session has the required scope', async () => {
+    const middleware = requireScope(Scope.WORKFLOW_READ);
+    const { ctx, next } = mockContext('http://localhost:3001/api/workflows', userSession);
+    await middleware(ctx as never, next);
+    expect(next).toHaveBeenCalled();
+    expect(ctx.json).not.toHaveBeenCalled();
+  });
+
+  it('should return 403 when session lacks the required scope', async () => {
+    const middleware = requireScope(Scope.PLUGIN_MANAGE);
+    const { ctx, next } = mockContext('http://localhost:3001/api/plugins', userSession);
+    await middleware(ctx as never, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: 'insufficient_permissions',
+        message: 'This operation requires additional permissions',
+      }),
+      403
+    );
+  });
+
+  it('should return 401 when no session at all', async () => {
+    const middleware = requireScope(Scope.WORKFLOW_READ);
+    const { ctx, next } = mockContext('http://localhost:3001/api/workflows');
+    await middleware(ctx as never, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: 'unauthorized',
+      }),
+      401
+    );
+  });
+
+  it('should allow admin to bypass any scope check', async () => {
+    const middleware = requireScope(Scope.PLUGIN_MANAGE);
+    const { ctx, next } = mockContext('http://localhost:3001/api/plugins', adminSession);
+    await middleware(ctx as never, next);
+    expect(next).toHaveBeenCalled();
+    expect(ctx.json).not.toHaveBeenCalled();
+  });
+
+  it('should accept an array of scopes (any match)', async () => {
+    const middleware = requireScope([Scope.PLUGIN_MANAGE, Scope.WORKFLOW_READ]);
+    const { ctx, next } = mockContext('http://localhost:3001/api/mixed', userSession);
+    await middleware(ctx as never, next);
+    // userSession has WORKFLOW_READ, so should pass
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should return 403 when none of the array scopes match', async () => {
+    const middleware = requireScope([Scope.PLUGIN_MANAGE, Scope.SETTINGS_WRITE]);
+    const { ctx, next } = mockContext('http://localhost:3001/api/admin-op', userSession);
+    await middleware(ctx as never, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: 'insufficient_permissions',
+      }),
+      403
+    );
+  });
+
+  it('should not leak user scopes in 403 response', async () => {
+    const middleware = requireScope(Scope.SETTINGS_WRITE);
+    const { ctx, next } = mockContext('http://localhost:3001/api/settings', userSession);
+    await middleware(ctx as never, next);
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.not.objectContaining({
+        required: expect.anything(),
+        provided: expect.anything(),
+      }),
+      expect.anything()
+    );
+  });
+});

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @brika/auth - Plugin Tests
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { container } from '@brika/di';
+import { auth } from '../plugin';
+
+const testDataDir = join(tmpdir(), `brika-test-${Date.now()}`);
+
+/** Stub server that records middleware and routes */
+function createMockServer() {
+  const middleware: unknown[] = [];
+  const routes: unknown[] = [];
+  return {
+    addMiddleware(mw: unknown) {
+      middleware.push(mw);
+    },
+    addRoutes(r: unknown[]) {
+      routes.push(...r);
+    },
+    middleware,
+    routes,
+  };
+}
+
+describe('Auth Plugin', () => {
+  beforeEach(() => {
+    container.clearInstances();
+  });
+
+  it('should create a bootstrap plugin', () => {
+    const plugin = auth({
+      dataDir: testDataDir,
+    });
+
+    expect(plugin.name).toBe('auth');
+    expect(typeof plugin.setup).toBe('function');
+    expect(typeof plugin.onStart).toBe('function');
+    expect(typeof plugin.onStop).toBe('function');
+  });
+
+  it('should register services and middleware when server is provided', () => {
+    const server = createMockServer();
+    const plugin = auth({
+      dataDir: testDataDir,
+      server,
+    });
+
+    plugin.setup?.();
+
+    expect(server.middleware.length).toBe(1);
+    expect(server.routes.length).toBeGreaterThan(0);
+
+    plugin.onStop?.();
+  });
+
+  it('should work without server (CLI mode)', () => {
+    const plugin = auth({
+      dataDir: testDataDir,
+    });
+
+    plugin.setup?.();
+    plugin.onStop?.();
+  });
+
+  it('should go through full lifecycle', async () => {
+    const plugin = auth({
+      dataDir: testDataDir,
+    });
+
+    plugin.setup?.();
+    await plugin.onStart?.();
+    plugin.onStop?.();
+  });
+});

package/src/__tests__/requireSession.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @brika/auth - requireSession Tests
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { Forbidden, Unauthorized } from '@brika/router';
+import { requireSession } from '../server/requireSession';
+import type { Session } from '../types';
+import { Role, Scope } from '../types';
+
+function mockCtx(session: Session | null) {
+  return {
+    get(key: string): unknown {
+      if (key === 'session') {
+        return session;
+      }
+      return undefined;
+    },
+  };
+}
+
+const adminSession: Session = {
+  id: 'sess-1',
+  userId: 'user-1',
+  userEmail: 'admin@test.com',
+  userName: 'Admin',
+  userRole: Role.ADMIN,
+  scopes: [Scope.ADMIN_ALL],
+};
+
+const userSession: Session = {
+  id: 'sess-2',
+  userId: 'user-2',
+  userEmail: 'user@test.com',
+  userName: 'User',
+  userRole: Role.USER,
+  scopes: [Scope.WORKFLOW_READ, Scope.WORKFLOW_WRITE, Scope.BOARD_READ],
+};
+
+describe('requireSession', () => {
+  it('should return session when present (no scope)', () => {
+    const session = requireSession(mockCtx(userSession));
+    expect(session).toBe(userSession);
+  });
+
+  it('should throw Unauthorized when no session', () => {
+    expect(() => requireSession(mockCtx(null))).toThrow(Unauthorized);
+  });
+
+  it('should return session when scope matches', () => {
+    const session = requireSession(mockCtx(userSession), Scope.WORKFLOW_READ);
+    expect(session).toBe(userSession);
+  });
+
+  it('should throw Forbidden when scope does not match', () => {
+    expect(() => requireSession(mockCtx(userSession), Scope.ADMIN_ALL)).toThrow(Forbidden);
+  });
+
+  it('should allow admin to access any scope', () => {
+    const session = requireSession(mockCtx(adminSession), Scope.WORKFLOW_READ);
+    expect(session).toBe(adminSession);
+  });
+
+  it('should accept array of scopes (any match)', () => {
+    const session = requireSession(mockCtx(userSession), [Scope.ADMIN_ALL, Scope.WORKFLOW_READ]);
+    expect(session).toBe(userSession);
+  });
+
+  it('should throw Forbidden when no array scopes match', () => {
+    expect(() =>
+      requireSession(mockCtx(userSession), [Scope.ADMIN_ALL, Scope.PLUGIN_MANAGE])
+    ).toThrow(Forbidden);
+  });
+
+  it('should throw Unauthorized before checking scope when no session', () => {
+    expect(() => requireSession(mockCtx(null), Scope.ADMIN_ALL)).toThrow(Unauthorized);
+  });
+});

package/src/__tests__/routes-auth.test.ts

@@ -0,0 +1,248 @@
+/**
+ * @brika/auth - Auth Route Tests (login, logout, session info)
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { stub, useTestBed } from '@brika/di/testing';
+import type { Middleware } from '@brika/router';
+import { TestApp } from '@brika/router/testing';
+import { authProtectedRoutes, authPublicRoutes } from '../server/routes/auth';
+import { AuthService } from '../services/AuthService';
+import { UserService } from '../services/UserService';
+import { Role, Scope, type Session, type User } from '../types';
+
+const authRoutes = [...authPublicRoutes, ...authProtectedRoutes];
+
+import { getAuthConfig } from '../config';
+
+function withSession(session: Session): Middleware {
+  return async (c, next) => {
+    c.set('session', session);
+    await next();
+  };
+}
+
+const adminSession: Session = {
+  id: 'sess-admin',
+  userId: 'user-admin',
+  userEmail: 'admin@test.com',
+  userName: 'Admin',
+  userRole: Role.ADMIN,
+  scopes: [Scope.ADMIN_ALL],
+};
+
+const mockUser: User = {
+  id: 'user-admin',
+  email: 'admin@test.com',
+  name: 'Admin',
+  role: Role.ADMIN,
+  avatarHash: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  isActive: true,
+  scopes: [],
+};
+
+// ─── POST /login ────────────────────────────────────────────────────────────
+
+describe('POST /login', () => {
+  let app: ReturnType<typeof TestApp.create>;
+
+  useTestBed(() => {
+    stub(AuthService, {
+      login: async () => ({
+        token: 'tok-abc',
+        user: mockUser,
+        expiresIn: 604800,
+      }),
+    });
+    app = TestApp.create(authRoutes);
+  });
+
+  test('returns 200 with Set-Cookie on success', async () => {
+    const res = await app.post('/login', {
+      email: 'admin@test.com',
+      password: 'secret',
+    });
+    expect(res.status).toBe(200);
+
+    const body = res.body as {
+      user: User;
+    };
+    expect(body.user.email).toBe('admin@test.com');
+
+    const cookie = res.headers.get('set-cookie') ?? '';
+    expect(cookie).toContain(`${getAuthConfig().session.cookieName}=tok-abc`);
+    expect(cookie).toContain('HttpOnly');
+    expect(cookie).toContain('Max-Age=604800');
+  });
+
+  test('extracts IP from x-forwarded-for header', async () => {
+    let capturedIp: string | undefined;
+    stub(AuthService, {
+      login: async (_email: string, _password: string, ip?: string) => {
+        capturedIp = ip;
+        return {
+          token: 'tok',
+          user: mockUser,
+          expiresIn: 604800,
+        };
+      },
+    });
+    app = TestApp.create(authRoutes);
+
+    await app.post(
+      '/login',
+      {
+        email: 'a@b.com',
+        password: 'x',
+      },
+      {
+        headers: {
+          'x-forwarded-for': '10.0.0.1',
+        },
+      }
+    );
+    expect(capturedIp).toBe('10.0.0.1');
+  });
+
+  test('extracts IP from x-real-ip when x-forwarded-for is absent', async () => {
+    let capturedIp: string | undefined;
+    stub(AuthService, {
+      login: async (_email: string, _password: string, ip?: string) => {
+        capturedIp = ip;
+        return {
+          token: 'tok',
+          user: mockUser,
+          expiresIn: 604800,
+        };
+      },
+    });
+    app = TestApp.create(authRoutes);
+
+    await app.post(
+      '/login',
+      {
+        email: 'a@b.com',
+        password: 'x',
+      },
+      {
+        headers: {
+          'x-real-ip': '10.0.0.2',
+        },
+      }
+    );
+    expect(capturedIp).toBe('10.0.0.2');
+  });
+
+  test('returns 401 when credentials are invalid (service throws)', async () => {
+    stub(AuthService, {
+      login: async () => {
+        throw new Error('Invalid credentials');
+      },
+    });
+    app = TestApp.create(authRoutes);
+
+    const res = await app.post('/login', {
+      email: 'bad@test.com',
+      password: 'wrong',
+    });
+    expect(res.status).toBe(401);
+    const body = res.body as {
+      error: string;
+    };
+    expect(body.error).toBe('Invalid credentials');
+  });
+});
+
+// ─── POST /logout ───────────────────────────────────────────────────────────
+
+describe('POST /logout — with session', () => {
+  let app: ReturnType<typeof TestApp.create>;
+  let revokedId: string | undefined;
+
+  useTestBed(() => {
+    revokedId = undefined;
+    stub(AuthService, {
+      logout: (id: string) => {
+        revokedId = id;
+      },
+    });
+    app = TestApp.create(authRoutes, [withSession(adminSession)]);
+  });
+
+  test('clears session cookie when logged in', async () => {
+    const res = await app.post('/logout');
+
+    expect(res.status).toBe(200);
+    expect(revokedId).toBe('sess-admin');
+
+    const cookie = res.headers.get('set-cookie') ?? '';
+    expect(cookie).toContain(`${getAuthConfig().session.cookieName}=;`);
+    expect(cookie).toContain('Max-Age=0');
+  });
+});
+
+describe('POST /logout — without session', () => {
+  let app: ReturnType<typeof TestApp.create>;
+
+  useTestBed(() => {
+    stub(AuthService, {
+      logout: () => {},
+    });
+    // No session middleware — ctx.get('session') returns null
+    app = TestApp.create(authRoutes);
+  });
+
+  test('returns 200 with empty cookie when no session (silent logout)', async () => {
+    const res = await app.post('/logout');
+
+    expect(res.status).toBe(200);
+    const body = res.body as {
+      ok: boolean;
+    };
+    expect(body.ok).toBe(true);
+
+    const cookie = res.headers.get('set-cookie') ?? '';
+    expect(cookie).toContain('Max-Age=0');
+  });
+});
+
+// ─── GET /session ───────────────────────────────────────────────────────────
+
+describe('GET /session — authenticated', () => {
+  let app: ReturnType<typeof TestApp.create>;
+
+  useTestBed(() => {
+    stub(UserService, {
+      getUser: () => mockUser,
+    });
+    app = TestApp.create(authRoutes, [withSession(adminSession)]);
+  });
+
+  test('returns user and scopes', async () => {
+    const res = await app.get('/session');
+    expect(res.status).toBe(200);
+
+    const body = res.body as {
+      user: User;
+      scopes: Scope[];
+    };
+    expect(body.user.email).toBe('admin@test.com');
+    expect(body.scopes).toEqual([Scope.ADMIN_ALL]);
+  });
+});
+
+describe('GET /session — unauthenticated', () => {
+  let app: ReturnType<typeof TestApp.create>;
+
+  useTestBed(() => {
+    stub(UserService);
+    app = TestApp.create(authRoutes);
+  });
+
+  test('returns 401 without session', async () => {
+    const res = await app.get('/session');
+    expect(res.status).toBe(401);
+  });
+});