@brika/auth 0.1.1

package/src/react/hooks.ts

@@ -0,0 +1,128 @@
+/**
+ * @brika/auth/react - Hooks
+ *
+ * React hooks for authentication
+ */
+
+import { useContext, useMemo } from 'react';
+import { canAccess, canAccessAll, Features } from '../middleware/canAccess';
+import { Scope } from '../types';
+import { AuthContext, AuthContextValue } from './AuthProvider';
+
+/**
+ * Use authentication context
+ *
+ * @example
+ * ```tsx
+ * const { user, login, logout } = useAuth();
+ * ```
+ */
+export function useAuth(): AuthContextValue {
+  const context = useContext(AuthContext);
+
+  if (!context) {
+    throw new Error('useAuth must be used within <AuthProvider>');
+  }
+
+  return context;
+}
+
+/**
+ * Check if user has access to a scope
+ *
+ * @example
+ * ```tsx
+ * const canEdit = useCanAccess(Scope.WORKFLOW_WRITE);
+ * ```
+ */
+export function useCanAccess(required: Scope | Scope[] | null): boolean {
+  const { session } = useAuth();
+
+  return useMemo(() => {
+    if (!required || !session) {
+      return false;
+    }
+    return canAccess((session.scopes || []) as Scope[], required);
+  }, [required, session?.scopes]);
+}
+
+/**
+ * Check if user has all required scopes
+ *
+ * @example
+ * ```tsx
+ * const canManage = useCanAccessAll([Scope.ADMIN_ALL]);
+ * ```
+ */
+export function useCanAccessAll(required: Scope[] | null): boolean {
+  const { session } = useAuth();
+
+  return useMemo(() => {
+    if (!required || !session) {
+      return false;
+    }
+    return canAccessAll((session.scopes || []) as Scope[], required);
+  }, [required, session?.scopes]);
+}
+
+/**
+ * Get feature permissions
+ *
+ * @example
+ * ```tsx
+ * const perms = useFeaturePermissions(Features.Workflow);
+ * if (perms.execute) {
+ *   // show execute button
+ * }
+ * ```
+ */
+export function useFeaturePermissions<
+  T extends Record<string, boolean | ((scopes: Scope[]) => boolean)>,
+>(featurePermissions: T): Record<keyof T, boolean> {
+  const { session } = useAuth();
+
+  return useMemo(() => {
+    const scopes = (session?.scopes ?? []) as Scope[];
+    return Object.fromEntries(
+      Object.entries(featurePermissions).map(([key, checker]) => {
+        if (!session) {
+          return [key, false];
+        }
+        const value = typeof checker === 'function' ? checker(scopes) : checker;
+        return [key, value];
+      })
+    ) as Record<keyof T, boolean>;
+  }, [session?.scopes]);
+}
+
+/**
+ * Check if user is loading auth state
+ */
+export function useAuthLoading(): boolean {
+  const { isLoading } = useAuth();
+  return isLoading;
+}
+
+/**
+ * Get current user
+ */
+export function useUser() {
+  const { user } = useAuth();
+  return user;
+}
+
+/**
+ * Get current session
+ */
+export function useSession() {
+  const { session } = useAuth();
+  return session;
+}
+
+/**
+ * Get auth error
+ */
+export function useAuthError() {
+  const { error } = useAuth();
+  return error;
+}

package/src/react/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @brika/auth/react
+ *
+ * React hooks and components for authentication.
+ * Use this in your Brika UI React app.
+ *
+ * @example
+ * ```tsx
+ * import { AuthProvider, useAuth } from '@brika/auth/react';
+ *
+ * function App() {
+ *   return (
+ *     // No apiUrl needed - uses window.location.origin
+ *     <AuthProvider>
+ *       <Dashboard />
+ *     </AuthProvider>
+ *   );
+ * }
+ *
+ * function Dashboard() {
+ *   const { user, login, logout } = useAuth();
+ *   const canEdit = useCanAccess(Scope.WORKFLOW_WRITE);
+ *
+ *   return (
+ *     <>
+ *       <h1>Hello, {user?.name}!</h1>
+ *       {canEdit && <EditButton />}
+ *       <button onClick={logout}>Logout</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+
+export {
+  AuthContext,
+  type AuthContextValue,
+  AuthProvider,
+  type AuthProviderProps,
+} from './AuthProvider';
+export {
+  useAuth,
+  useAuthError,
+  useAuthLoading,
+  useCanAccess,
+  useCanAccessAll,
+  useFeaturePermissions,
+  useSession,
+  useUser,
+} from './hooks';
+export { type WithScopeGuardOptions, withOptionalScope, withScopeGuard } from './withScopeGuard';

package/src/react/withScopeGuard.tsx

@@ -0,0 +1,73 @@
+/**
+ * @brika/auth/react - withScopeGuard HOC
+ *
+ * Higher-order component to protect components with scope requirements.
+ */
+
+import React from 'react';
+import { Scope } from '../types';
+import { useCanAccess } from './hooks';
+
+export interface WithScopeGuardOptions {
+  fallback?: React.ReactNode;
+}
+
+const DEFAULT_FALLBACK = (
+  <div>
+    <h1>Unauthorized</h1>
+    <p>You don't have permission to access this page.</p>
+  </div>
+);
+
+/**
+ * HOC to protect a component with scope requirement.
+ *
+ * @example
+ * ```tsx
+ * const ProtectedEditor = withScopeGuard(
+ *   WorkflowEditor,
+ *   Scope.WORKFLOW_WRITE,
+ *   { fallback: <UnauthorizedPage /> }
+ * );
+ * ```
+ */
+export function withScopeGuard<P extends object>(
+  Component: React.ComponentType<P>,
+  requiredScopes: Scope | Scope[] | null,
+  options?: WithScopeGuardOptions
+): React.ComponentType<P> {
+  const displayName = `withScopeGuard(${Component.displayName || Component.name})`;
+
+  const Wrapper = (props: P) => {
+    const canAccess = useCanAccess(requiredScopes);
+
+    if (!canAccess) {
+      return options?.fallback !== undefined ? options.fallback : DEFAULT_FALLBACK;
+    }
+
+    return <Component {...props} />;
+  };
+
+  Wrapper.displayName = displayName;
+
+  return Wrapper;
+}
+
+/**
+ * HOC to hide component if user lacks scope
+ * (renders nothing instead of fallback)
+ *
+ * @example
+ * ```tsx
+ * const OptionalButton = withOptionalScope(AdminButton, Scope.ADMIN_ALL);
+ * // Returns null if user doesn't have admin scope
+ * ```
+ */
+export function withOptionalScope<P extends object>(
+  Component: React.ComponentType<P>,
+  requiredScopes: Scope | Scope[] | null
+): React.ComponentType<P> {
+  return withScopeGuard(Component, requiredScopes, {
+    fallback: null,
+  });
+}

package/src/roles.ts

@@ -0,0 +1,40 @@
+/**
+ * @brika/auth - Roles
+ *
+ * User roles determine the default set of scopes granted to a user.
+ *
+ * To add a new role:
+ *   1. Add an entry below with its default scopes
+ */
+
+import { defineRoles } from './lib/define-roles';
+import { Scope } from './scopes';
+
+export const { Role, ROLE_SCOPES } = defineRoles({
+  ADMIN: {
+    value: 'admin',
+    defaultScopes: [Scope.ADMIN_ALL],
+  },
+  USER: {
+    value: 'user',
+    defaultScopes: [
+      Scope.WORKFLOW_READ,
+      Scope.WORKFLOW_WRITE,
+      Scope.WORKFLOW_EXECUTE,
+      Scope.BOARD_READ,
+      Scope.BOARD_WRITE,
+      Scope.PLUGIN_READ,
+      Scope.SETTINGS_READ,
+    ],
+  },
+  GUEST: {
+    value: 'guest',
+    defaultScopes: [Scope.WORKFLOW_READ, Scope.BOARD_READ, Scope.PLUGIN_READ],
+  },
+  SERVICE: {
+    value: 'service',
+    defaultScopes: [],
+  },
+});
+
+export type Role = (typeof Role)[keyof typeof Role];

package/src/schemas.ts

@@ -0,0 +1,112 @@
+/**
+ * @brika/auth - Zod Schemas for Validation
+ */
+
+import { z } from 'zod';
+import { getAuthConfig } from './config';
+import { Role } from './roles';
+import { Scope } from './scopes';
+
+const roleValues = Object.values(Role) as [Role, ...Role[]];
+const scopeValues = Object.values(Scope) as [Scope, ...Scope[]];
+
+export const RoleSchema = z.enum(roleValues);
+
+export const ScopeSchema = z.enum(scopeValues);
+
+export const EmailSchema = z.string().email('Invalid email address').toLowerCase();
+
+export const NameSchema = z.string().min(2, 'Name must be at least 2 characters').max(255);
+
+/**
+ * Password schema — reads config lazily so it respects runtime overrides.
+ * Uses z.string() + superRefine so all rules are evaluated at validation time.
+ * Max 72 chars: bcrypt silently truncates beyond this, so enforce it explicitly.
+ */
+export const PasswordSchema = z
+  .string()
+  .max(72, 'Max 72 characters')
+  .superRefine((v, ctx) => {
+    const { password } = getAuthConfig();
+
+    if (v.length < password.minLength) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `Min ${password.minLength} characters`,
+      });
+    }
+    if (password.requireUppercase && !/[A-Z]/.test(v)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Need uppercase letter (A-Z)',
+      });
+    }
+    if (password.requireNumbers && !/\d/.test(v)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Need number (0-9)',
+      });
+    }
+    if (password.requireSpecial && !password.specialChars.test(v)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Need special character (!@#$%^&*...)',
+      });
+    }
+  });
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: EmailSchema,
+  name: NameSchema,
+  role: RoleSchema,
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  isActive: z.boolean().default(true),
+});
+
+export const SessionSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  userEmail: z.string().email(),
+  userName: z.string(),
+  userRole: RoleSchema,
+  scopes: z.array(ScopeSchema),
+});
+
+export const LoginSchema = z.object({
+  email: EmailSchema,
+  password: z.string().min(1),
+});
+
+export const CreateUserSchema = z.object({
+  email: EmailSchema,
+  name: NameSchema,
+  role: RoleSchema.default(Role.USER),
+  password: PasswordSchema.optional(),
+});
+
+export const SetupSchema = z.object({
+  email: EmailSchema,
+  name: NameSchema,
+  password: PasswordSchema,
+});
+
+export const CreateApiTokenSchema = z.object({
+  name: z.string().min(1).max(255),
+  scopes: z.array(ScopeSchema),
+  expiresAt: z.date().optional(),
+});
+
+/**
+ * Validate a password against the policy.
+ * Returns the first error message, or undefined if valid.
+ * Compatible with @clack/prompts validate functions.
+ */
+export function validatePassword(value: string): string | undefined {
+  const result = PasswordSchema.safeParse(value);
+  if (result.success) {
+    return undefined;
+  }
+  return result.error.issues[0]?.message;
+}

package/src/scopes.ts

@@ -0,0 +1,60 @@
+/**
+ * @brika/auth - Scopes
+ *
+ * Permission scopes control what actions a user can perform.
+ * Each user has an explicit allow-list of scopes stored in DB.
+ * New users receive ROLE_SCOPES[role] as defaults.
+ *
+ * To add a new scope:
+ *   1. Add an entry to the scopes object below
+ *   2. Optionally add it to ROLE_SCOPES in role-scopes.ts
+ */
+
+import { defineScopes } from './lib/define-scopes';
+
+export const { Scope, SCOPES_REGISTRY } = defineScopes({
+  scopes: {
+    ADMIN_ALL: {
+      value: 'admin:*',
+      description: 'Full administrative access',
+    },
+    WORKFLOW_READ: {
+      value: 'workflow:read',
+      description: 'Read workflows',
+    },
+    WORKFLOW_WRITE: {
+      value: 'workflow:write',
+      description: 'Create and edit workflows',
+    },
+    WORKFLOW_EXECUTE: {
+      value: 'workflow:execute',
+      description: 'Execute workflows',
+    },
+    BOARD_READ: {
+      value: 'board:read',
+      description: 'Read boards',
+    },
+    BOARD_WRITE: {
+      value: 'board:write',
+      description: 'Create and edit boards',
+    },
+    PLUGIN_READ: {
+      value: 'plugin:read',
+      description: 'List and read plugins',
+    },
+    PLUGIN_MANAGE: {
+      value: 'plugin:manage',
+      description: 'Install and uninstall plugins',
+    },
+    SETTINGS_READ: {
+      value: 'settings:read',
+      description: 'Read system settings',
+    },
+    SETTINGS_WRITE: {
+      value: 'settings:write',
+      description: 'Modify system settings',
+    },
+  },
+});
+
+export type Scope = (typeof Scope)[keyof typeof Scope];

package/src/server/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @brika/auth/server
+ *
+ * Server-side authentication module.
+ *
+ * @example
+ * ```ts
+ * import { auth } from '@brika/auth/server';
+ *
+ * // Hub: with API server
+ * await bootstrap()
+ *   .use(auth({ dataDir, server: inject(ApiServer) }))
+ *   .start();
+ *
+ * // CLI: services + DB only
+ * await bootstrapCLI()
+ *   .use(auth({ dataDir }))
+ *   .start();
+ * ```
+ */
+
+export {
+  canAccess,
+  canAccessAll,
+  createPermissionChecker,
+  Features,
+} from '../middleware/canAccess';
+// 🛡️ Middleware
+export { type AuthContext, requireAuth } from '../middleware/requireAuth';
+export { requireScope } from '../middleware/requireScope';
+export { verifyToken } from '../middleware/verifyToken';
+export { auth } from '../plugin';
+// 🏗️ Services
+export { AuthService } from '../services/AuthService';
+export { ScopeService } from '../services/ScopeService';
+export { SessionService } from '../services/SessionService';
+export { UserService } from '../services/UserService';
+// 🎯 Setup & Plugin
+export { openAuthDatabase, setupAuthServices } from '../setup';
+// 🛠️ Route Helpers
+export { requireSession } from './requireSession';
+// 🌐 Routes
+export { allAuthRoutes as authRoutes } from './routes/index';
+export { serveImage } from './serveImage';

package/src/server/requireSession.ts

@@ -0,0 +1,44 @@
+/**
+ * @brika/auth/server - requireSession
+ *
+ * Extract authenticated session from route context.
+ * Throws 401 Unauthorized if no session.
+ * Optionally validates scope — throws 403 Forbidden if missing required scope.
+ *
+ * @example
+ * ```ts
+ * // Just auth check
+ * const session = requireSession(ctx);
+ *
+ * // Auth + scope check (throws 403 if missing)
+ * const session = requireSession(ctx, Scope.ADMIN_ALL);
+ *
+ * // Auth + any-of scope check
+ * const session = requireSession(ctx, [Scope.WORKFLOW_READ, Scope.ADMIN_ALL]);
+ * ```
+ */
+
+import { Forbidden, Unauthorized } from '@brika/router';
+import { canAccess } from '../middleware/canAccess';
+import type { Scope, Session } from '../types';
+
+export function requireSession(
+  ctx: {
+    get(key: string): unknown;
+  },
+  scope?: Scope | Scope[]
+): Session {
+  const session = ctx.get('session') as Session | null;
+  if (!session) {
+    throw new Unauthorized();
+  }
+
+  if (scope !== undefined) {
+    if (!canAccess(session.scopes, scope)) {
+      const required = Array.isArray(scope) ? scope : [scope];
+      throw new Forbidden(`Insufficient permissions. Required: ${required.join(', ')}`);
+    }
+  }
+
+  return session;
+}

package/src/server/routes/auth.ts

@@ -0,0 +1,102 @@
+/**
+ * Auth routes — login, logout, session info
+ */
+
+import { inject } from '@brika/di';
+import { rateLimit, route } from '@brika/router';
+import { LoginSchema } from '../../schemas';
+import { AuthService } from '../../services/AuthService';
+import { UserService } from '../../services/UserService';
+import type { Session } from '../../types';
+import { requireSession } from '../requireSession';
+import { sessionCookie } from './cookie';
+
+/** POST /login — Login with email and password */
+const login = route.post({
+  path: '/login',
+  middleware: [
+    rateLimit({
+      window: 60,
+      max: 5,
+    }),
+  ],
+  body: LoginSchema,
+  handler: async (ctx) => {
+    const authService = inject(AuthService);
+    const { email, password } = ctx.body;
+    const ip =
+      ctx.req.headers.get('x-forwarded-for') ?? ctx.req.headers.get('x-real-ip') ?? undefined;
+    const userAgent = ctx.req.headers.get('user-agent') ?? undefined;
+
+    try {
+      const result = await authService.login(email, password, ip, userAgent);
+
+      return new Response(
+        JSON.stringify({
+          user: result.user,
+        }),
+        {
+          headers: {
+            'Content-Type': 'application/json',
+            'Set-Cookie': sessionCookie(result.token, result.expiresIn),
+          },
+        }
+      );
+    } catch {
+      return new Response(
+        JSON.stringify({
+          error: 'Invalid credentials',
+        }),
+        {
+          status: 401,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        }
+      );
+    }
+  },
+});
+
+/** POST /logout — Logout and revoke current session */
+const logout = route.post({
+  path: '/logout',
+  handler: (ctx) => {
+    const authService = inject(AuthService);
+    const session = ctx.get('session') as Session | null;
+
+    if (session) {
+      authService.logout(session.id);
+    }
+
+    return new Response(
+      JSON.stringify({
+        ok: true,
+      }),
+      {
+        headers: {
+          'Content-Type': 'application/json',
+          'Set-Cookie': sessionCookie('', 0),
+        },
+      }
+    );
+  },
+});
+
+/** GET /session — Get current session info */
+const sessionInfo = route.get({
+  path: '/session',
+  handler: (ctx) => {
+    const session = requireSession(ctx);
+    const userService = inject(UserService);
+    const user = userService.getUser(session.userId);
+
+    return {
+      user,
+      scopes: session.scopes,
+    };
+  },
+});
+
+export const authPublicRoutes = [login];
+export const authProtectedRoutes = [logout, sessionInfo];

package/src/server/routes/cookie.ts

@@ -0,0 +1,7 @@
+import { getAuthConfig } from '../../config';
+
+/** Build a Set-Cookie header value for the session token. */
+export function sessionCookie(token: string, maxAge: number): string {
+  const name = getAuthConfig().session.cookieName;
+  return `${name}=${token}; HttpOnly; Secure; Path=/api; Max-Age=${maxAge}; SameSite=Lax`;
+}

package/src/server/routes/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @brika/auth/server - All Routes
+ *
+ * Combines auth, session, profile, user, and scope routes.
+ * Login and scopes are public; everything else requires authentication.
+ */
+
+import { combineRoutes, group } from '@brika/router';
+import { requireAuth } from '../../middleware/requireAuth';
+import { authProtectedRoutes, authPublicRoutes } from './auth';
+import { profileRoutes } from './profile';
+import { scopeRoutes } from './scopes';
+import { sessionRoutes } from './sessions';
+import { setupRoutes } from './setup';
+import { userRoutes } from './users';
+
+export const allAuthRoutes = combineRoutes(
+  group({
+    prefix: '/api/auth',
+    routes: [authPublicRoutes, scopeRoutes],
+  }),
+  group({
+    prefix: '/api/auth/setup',
+    routes: [setupRoutes],
+  }),
+  group({
+    prefix: '/api/auth',
+    middleware: [requireAuth()],
+    routes: [authProtectedRoutes, sessionRoutes, profileRoutes],
+  }),
+  userRoutes
+);