@brika/auth 0.1.1

package/src/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * @brika/auth - Constants
+ *
+ * Re-exports for backward compatibility.
+ * Canonical homes: scopes.ts, config.ts
+ */
+
+export { AUTH_DEFAULTS, getAuthConfig } from './config';
+export { ROLE_SCOPES } from './roles';
+export { SCOPES_REGISTRY } from './scopes';

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @brika/auth
+ *
+ * Shared types and constants for authentication system.
+ *
+ * For server-side: import { ... } from '@brika/auth/server'
+ * For client-side: import { ... } from '@brika/auth/client'
+ * For React: import { ... } from '@brika/auth/react'
+ */
+
+export * from './config';
+export * from './constants';
+export * from './roles';
+export * from './schemas';
+export * from './scopes';
+export * from './types';

package/src/lib/define-roles.ts

@@ -0,0 +1,35 @@
+/**
+ * @brika/auth - Role builder
+ *
+ * Takes a declarative role config and produces typed Role constant
+ * and ROLE_SCOPES mapping.
+ */
+
+interface RoleDef<TScope extends string> {
+  readonly value: string;
+  readonly defaultScopes: readonly TScope[];
+}
+
+export interface BuiltRoles<TDefs extends Record<string, RoleDef<string>>> {
+  /** Role constant — e.g. `Role.ADMIN` → `'admin'` */
+  Role: { readonly [K in keyof TDefs]: TDefs[K]['value'] };
+  /** Default scopes for each role (keyed by role value). */
+  ROLE_SCOPES: { [K in keyof TDefs as TDefs[K]['value']]: TDefs[K]['defaultScopes'][number][] };
+}
+
+export function defineRoles<const TDefs extends Record<string, RoleDef<string>>>(
+  defs: TDefs
+): BuiltRoles<TDefs> {
+  const Role = Object.fromEntries(
+    Object.entries(defs).map(([k, v]) => [k, v.value])
+  ) as BuiltRoles<TDefs>['Role'];
+
+  const ROLE_SCOPES = Object.fromEntries(
+    Object.entries(defs).map(([, v]) => [v.value, [...v.defaultScopes]])
+  ) as BuiltRoles<TDefs>['ROLE_SCOPES'];
+
+  return {
+    Role,
+    ROLE_SCOPES,
+  };
+}

package/src/lib/define-scopes.ts

@@ -0,0 +1,48 @@
+/**
+ * @brika/auth - Scope builder
+ *
+ * Takes a declarative scope/role config and produces typed Scope constant,
+ * ROLE_SCOPES mapping, and SCOPES_REGISTRY metadata.
+ */
+
+interface ScopeDef {
+  readonly value: string;
+  readonly description: string;
+}
+
+export interface ScopeRegistryEntry {
+  description: string;
+  category: string;
+}
+
+export interface BuiltScopes<TDefs extends Record<string, ScopeDef>> {
+  /** Scope constant — e.g. `Scope.WORKFLOW_READ` → `'workflow:read'` */
+  Scope: { readonly [K in keyof TDefs]: TDefs[K]['value'] };
+  /** Scope metadata for UI display. */
+  SCOPES_REGISTRY: Record<TDefs[keyof TDefs]['value'], ScopeRegistryEntry>;
+}
+
+export function defineScopes<const TDefs extends Record<string, ScopeDef>>(config: {
+  scopes: TDefs;
+}): BuiltScopes<TDefs> {
+  const { scopes } = config;
+
+  const Scope = Object.fromEntries(
+    Object.entries(scopes).map(([k, v]) => [k, v.value])
+  ) as BuiltScopes<TDefs>['Scope'];
+
+  const SCOPES_REGISTRY = Object.fromEntries(
+    Object.values(scopes).map((def) => [
+      def.value,
+      {
+        description: def.description,
+        category: def.value.split(':')[0],
+      },
+    ])
+  ) as BuiltScopes<TDefs>['SCOPES_REGISTRY'];
+
+  return {
+    Scope,
+    SCOPES_REGISTRY,
+  };
+}

package/src/middleware/canAccess.ts

@@ -0,0 +1,126 @@
+/**
+ * @brika/auth - canAccess Helper
+ * Check scope/permission without throwing (returns boolean)
+ */
+
+import { Scope } from '../types';
+
+/**
+ * Check if session/scopes can access a feature
+ * Returns boolean (safe for use in UI logic, conditionals, etc)
+ *
+ * @example
+ * ```ts
+ * const canEditWorkflow = canAccess(session.scopes, Scope.WORKFLOW_WRITE);
+ * if (canEditWorkflow) {
+ *   renderEditButton();
+ * }
+ *
+ * // In routes
+ * if (!canAccess(session.scopes, [Scope.ADMIN_ALL])) {
+ *   return forbidden();
+ * }
+ * ```
+ */
+export function canAccess(scopes: Scope[] | null | undefined, required: Scope | Scope[]): boolean {
+  if (!scopes || scopes.length === 0) {
+    return false;
+  }
+
+  const requiredScopes = Array.isArray(required) ? required : [required];
+
+  // Admin can access everything
+  if (scopes.includes(Scope.ADMIN_ALL)) {
+    return true;
+  }
+
+  // Check if has any required scope
+  return requiredScopes.some((scope) => scopes.includes(scope));
+}
+
+/**
+ * Check if session can access all required scopes
+ *
+ * @example
+ * ```ts
+ * const canManageUsers = canAccessAll(session.scopes, [
+ *   Scope.ADMIN_ALL,
+ * ]);
+ * ```
+ */
+export function canAccessAll(scopes: Scope[] | null | undefined, required: Scope[]): boolean {
+  if (!scopes || scopes.length === 0) {
+    return false;
+  }
+
+  // Admin can access everything
+  if (scopes.includes(Scope.ADMIN_ALL)) {
+    return true;
+  }
+
+  // Check if has all required scopes
+  return required.every((scope) => scopes.includes(scope));
+}
+
+/**
+ * Create a permission checker for a specific feature
+ * Useful for organizing feature flags
+ *
+ * @example
+ * ```ts
+ * const WorkflowPermissions = {
+ *   read: (scopes) => canAccess(scopes, Scope.WORKFLOW_READ),
+ *   write: (scopes) => canAccess(scopes, Scope.WORKFLOW_WRITE),
+ *   execute: (scopes) => canAccess(scopes, Scope.WORKFLOW_EXECUTE),
+ * };
+ *
+ * // Usage
+ * if (WorkflowPermissions.execute(session.scopes)) {
+ *   canRunWorkflow = true;
+ * }
+ * ```
+ */
+export function createPermissionChecker(
+  featureName: string,
+  scopeMap: Record<string, Scope | Scope[]>
+): Record<string, (scopes: Scope[] | null | undefined) => boolean> {
+  return Object.entries(scopeMap).reduce(
+    (acc, [action, scopes]) => {
+      acc[action] = (userScopes: Scope[] | null | undefined) => canAccess(userScopes, scopes);
+      return acc;
+    },
+    {} as Record<string, (scopes: Scope[] | null | undefined) => boolean>
+  );
+}
+
+/**
+ * Feature permission objects (pre-built for common features)
+ */
+export const Features = {
+  Workflow: createPermissionChecker('Workflow', {
+    read: Scope.WORKFLOW_READ,
+    write: Scope.WORKFLOW_WRITE,
+    execute: Scope.WORKFLOW_EXECUTE,
+    all: [Scope.WORKFLOW_READ, Scope.WORKFLOW_WRITE, Scope.WORKFLOW_EXECUTE],
+  }),
+
+  Board: createPermissionChecker('Board', {
+    read: Scope.BOARD_READ,
+    write: Scope.BOARD_WRITE,
+    all: [Scope.BOARD_READ, Scope.BOARD_WRITE],
+  }),
+
+  Plugin: createPermissionChecker('Plugin', {
+    read: Scope.PLUGIN_READ,
+    manage: Scope.PLUGIN_MANAGE,
+  }),
+
+  Settings: createPermissionChecker('Settings', {
+    read: Scope.SETTINGS_READ,
+    write: Scope.SETTINGS_WRITE,
+  }),
+
+  Admin: createPermissionChecker('Admin', {
+    all: Scope.ADMIN_ALL,
+  }),
+};

package/src/middleware/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @brika/auth - Middleware
+ */
+
+export {
+  canAccess,
+  canAccessAll,
+  createPermissionChecker,
+  Features,
+} from './canAccess';
+export { type AuthContext, requireAuth } from './requireAuth';
+export { requireScope } from './requireScope';
+export { verifyToken } from './verifyToken';

package/src/middleware/requireAuth.ts

@@ -0,0 +1,35 @@
+/**
+ * @brika/auth - requireAuth Middleware
+ * Enforce authentication (block unauthenticated requests)
+ */
+
+import type { HonoContext, Middleware } from '@brika/router';
+import { Session } from '../types';
+
+/**
+ * Hono middleware to enforce authentication.
+ * Returns 401 if no valid session.
+ */
+export function requireAuth(): Middleware {
+  return async (context: HonoContext, next: () => Promise<void>) => {
+    const session = context.get('session');
+
+    if (!session) {
+      return context.json(
+        {
+          error: 'Unauthorized',
+        },
+        401
+      );
+    }
+
+    await next();
+  };
+}
+
+/**
+ * Type for authenticated context
+ */
+export interface AuthContext {
+  session: Session;
+}

package/src/middleware/requireScope.ts

@@ -0,0 +1,46 @@
+/**
+ * @brika/auth - requireScope Middleware
+ * Enforce scope/permission requirements (throw 403 if missing)
+ */
+
+import { inject } from '@brika/di';
+import type { HonoContext, Middleware } from '@brika/router';
+import { ScopeService } from '../services/ScopeService';
+import { Scope, Session } from '../types';
+
+/**
+ * Hono middleware to enforce scope requirements.
+ * Returns 403 Forbidden if user lacks required scopes.
+ */
+export function requireScope(required: Scope | Scope[]): Middleware {
+  const scopeService = inject(ScopeService);
+
+  return async (context: HonoContext, next: () => Promise<void>) => {
+    const session = context.get('session') as Session | null;
+
+    if (!session) {
+      return context.json(
+        {
+          error: 'unauthorized',
+          message: 'Authentication required',
+        },
+        401
+      );
+    }
+
+    const requiredScopes = Array.isArray(required) ? required : [required];
+    const hasScope = requiredScopes.some((scope) => scopeService.hasScope(session.scopes, scope));
+
+    if (!hasScope) {
+      return context.json(
+        {
+          error: 'insufficient_permissions',
+          message: 'This operation requires additional permissions',
+        },
+        403
+      );
+    }
+
+    await next();
+  };
+}

package/src/middleware/verifyToken.ts

@@ -0,0 +1,52 @@
+/**
+ * @brika/auth - verifyToken Middleware
+ * Extract session token from cookie (or Authorization header) and validate against DB.
+ */
+
+import { inject } from '@brika/di';
+import type { HonoContext, Middleware } from '@brika/router';
+import { getAuthConfig } from '../config';
+import { SessionService } from '../services/SessionService';
+
+function getCookieValue(header: string | undefined, name: string): string | undefined {
+  if (!header) {
+    return undefined;
+  }
+  for (const pair of header.split(';')) {
+    const [key, ...rest] = pair.split('=');
+    if (key?.trim() === name) {
+      return rest.join('=').trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Middleware to verify session tokens.
+ * Reads token from HttpOnly cookie (browser) or Authorization header (API clients).
+ * Looks up token in DB, attaches session to context.
+ * Also updates last_seen_at (sliding expiration) and IP on each request.
+ */
+export function verifyToken(): Middleware {
+  const sessionService = inject(SessionService);
+
+  return async (context: HonoContext, next: () => Promise<void>) => {
+    const authHeader = context.req.header('Authorization');
+    const bearerToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
+    const token =
+      getCookieValue(context.req.header('Cookie'), getAuthConfig().session.cookieName) ??
+      bearerToken;
+
+    if (!token) {
+      context.set('session', null);
+      await next();
+      return;
+    }
+
+    const ip = context.req.header('x-forwarded-for') ?? context.req.header('x-real-ip');
+    const session = sessionService.validateSession(token, ip ?? undefined);
+
+    context.set('session', session);
+    await next();
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,86 @@
+/**
+ * @brika/auth - Bootstrap Plugin
+ *
+ * Single entry point: opens SQLite, registers services,
+ * optionally wires HTTP middleware + routes.
+ *
+ * @example Hub
+ * ```ts
+ * await bootstrap()
+ *   .use(auth({ dataDir, server: inject(ApiServer) }))
+ *   .start();
+ * ```
+ *
+ * @example CLI
+ * ```ts
+ * await bootstrapCLI()
+ *   .use(auth({ dataDir }))
+ *   .start();
+ * ```
+ */
+
+import type { Database } from 'bun:sqlite';
+import { join } from 'node:path';
+import { inject } from '@brika/di';
+import type { Middleware, RouteDefinition } from '@brika/router';
+import type { AuthConfig } from './config';
+import { verifyToken } from './middleware/verifyToken';
+import { allAuthRoutes as authRoutes } from './server/routes/index';
+import { SessionService } from './services/SessionService';
+import { openAuthDatabase, setupAuthServices } from './setup';
+
+interface ApiServer {
+  addMiddleware(mw: Middleware): void;
+  addRoutes(routes: RouteDefinition[]): void;
+}
+
+export interface AuthPluginOptions {
+  /** Root data directory (e.g. ~/.brika or .brika) */
+  dataDir: string;
+  /** API server — pass to enable HTTP middleware + routes (hub mode) */
+  server?: ApiServer;
+  /** Auth configuration overrides (session TTL, password policy, etc.) */
+  config?: AuthConfig;
+}
+
+/**
+ * Auth bootstrap plugin.
+ */
+export function auth(options: AuthPluginOptions) {
+  const { dataDir, server, config } = options;
+  let db: Database;
+  let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Run expired session cleanup every 6 hours */
+  const CLEANUP_INTERVAL = 6 * 60 * 60 * 1000;
+
+  return {
+    name: 'auth',
+
+    setup() {
+      db = openAuthDatabase(join(dataDir, 'auth.db'));
+      setupAuthServices(db, config);
+
+      if (server) {
+        server.addMiddleware(verifyToken());
+        server.addRoutes(authRoutes);
+      }
+    },
+
+    onStart() {
+      const sessionService = inject(SessionService);
+      // Initial cleanup on startup, then periodically
+      sessionService.cleanExpiredSessions();
+      cleanupTimer = setInterval(() => sessionService.cleanExpiredSessions(), CLEANUP_INTERVAL);
+      cleanupTimer.unref();
+    },
+
+    onStop() {
+      if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+      }
+      db?.close();
+    },
+  };
+}

package/src/react/AuthProvider.tsx

@@ -0,0 +1,105 @@
+/**
+ * Auth Provider — Session-based authentication context
+ *
+ * Usage:
+ *   <AuthProvider>
+ *     <App />
+ *   </AuthProvider>
+ */
+
+import React, { createContext, ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
+import { AuthClient, createAuthClient, Session } from '../client/AuthClient';
+
+export interface AuthContextType {
+  user: Session['user'] | null;
+  session: Session | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  /** True when no admin exists and initial setup is required. */
+  needsSetup: boolean;
+  error: string | null;
+  client: AuthClient;
+  /** Clear the client-side session (e.g. after a 401 response). Does not call logout API. */
+  clearSession: () => void;
+  /** Update the session without affecting setup state. Used during onboarding. */
+  updateSession: (session: Session) => void;
+  /** Refresh session from the server (re-fetches /api/auth/session). */
+  refreshSession: () => Promise<void>;
+}
+
+export type AuthContextValue = AuthContextType;
+
+export const AuthContext = createContext<AuthContextType | null>(null);
+
+export interface AuthProviderProps {
+  children: ReactNode;
+  apiUrl?: string;
+}
+
+export function AuthProvider({ children, apiUrl }: Readonly<AuthProviderProps>) {
+  const client = useMemo(
+    () =>
+      createAuthClient({
+        apiUrl,
+      }),
+    []
+  );
+
+  const [session, setSession] = useState<Session | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [needsSetup, setNeedsSetup] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Check for active session on mount (cookie is HttpOnly, invisible to JS)
+  useEffect(() => {
+    const loadSession = async () => {
+      try {
+        setIsLoading(true);
+        const [loaded, status] = await Promise.all([
+          client.getSession(),
+          client.checkSetupStatus(),
+        ]);
+        setSession(loaded);
+        setNeedsSetup(status.needsSetup);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Failed to load session';
+        setError(message);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    loadSession();
+  }, [client]);
+
+  const clearSession = useCallback(() => setSession(null), []);
+  const updateSession = useCallback((s: Session) => setSession(s), []);
+
+  const refreshSession = useCallback(async () => {
+    try {
+      const [loaded, status] = await Promise.all([client.getSession(), client.checkSetupStatus()]);
+      setSession(loaded);
+      setNeedsSetup(status.needsSetup);
+    } catch {
+      setSession(null);
+    }
+  }, [client]);
+
+  const value = useMemo<AuthContextType>(
+    () => ({
+      user: session?.user || null,
+      session,
+      isAuthenticated: session !== null,
+      isLoading,
+      needsSetup,
+      error,
+      client,
+      clearSession,
+      updateSession,
+      refreshSession,
+    }),
+    [session, isLoading, needsSetup, error, client, clearSession, updateSession, refreshSession]
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}