@brika/auth 0.1.1

package/src/services/ScopeService.ts

@@ -0,0 +1,94 @@
+/**
+ * @brika/auth - ScopeService
+ * Handles scope validation and permission checks
+ */
+
+import { injectable } from '@brika/di';
+import { ROLE_SCOPES, SCOPES_REGISTRY } from '../constants';
+import { Role, Scope } from '../types';
+
+/**
+ * Service for managing scopes and permissions
+ */
+@injectable()
+export class ScopeService {
+  /**
+   * Check if scope is valid
+   */
+  isValidScope(scope: string): scope is Scope {
+    return Object.values(Scope).includes(scope as Scope);
+  }
+
+  /**
+   * Validate array of scopes
+   */
+  validateScopes(scopes: unknown[]): Scope[] {
+    if (!Array.isArray(scopes)) {
+      return [];
+    }
+
+    return scopes.filter((s) => this.isValidScope(s as string)) as Scope[];
+  }
+
+  /**
+   * Get scopes for a user based on role
+   */
+  getScopesForRole(role: Role): Scope[] {
+    return ROLE_SCOPES[role] || [];
+  }
+
+  /**
+   * Check if scopes include required scope
+   */
+  hasScope(scopes: Scope[], requiredScope: Scope): boolean {
+    if (requiredScope === Scope.ADMIN_ALL) {
+      return scopes.includes(Scope.ADMIN_ALL);
+    }
+
+    return scopes.includes(requiredScope) || scopes.includes(Scope.ADMIN_ALL);
+  }
+
+  /**
+   * Check if scopes include any in list
+   */
+  hasScopeAny(scopes: Scope[], required: Scope[]): boolean {
+    return required.some((scope) => this.hasScope(scopes, scope));
+  }
+
+  /**
+   * Check if scopes include all in list
+   */
+  hasScopeAll(scopes: Scope[], required: Scope[]): boolean {
+    return required.every((scope) => this.hasScope(scopes, scope));
+  }
+
+  /**
+   * Get all available scopes
+   */
+  getAllScopes(): Scope[] {
+    return Object.values(Scope) as Scope[];
+  }
+
+  /**
+   * Get scopes by category
+   */
+  getScopesByCategory(category: string): Scope[] {
+    return Object.entries(SCOPES_REGISTRY)
+      .filter(([, info]) => info.category === category)
+      .map(([scope]) => scope as Scope);
+  }
+
+  /**
+   * Get scope description
+   */
+  getScopeDescription(scope: Scope): string {
+    return SCOPES_REGISTRY[scope]?.description || 'Unknown scope';
+  }
+
+  /**
+   * Get all scopes with descriptions
+   */
+  getRegistry() {
+    return SCOPES_REGISTRY;
+  }
+}

package/src/services/SessionService.ts

@@ -0,0 +1,245 @@
+/**
+ * @brika/auth - SessionService
+ * Manages server-side sessions stored in SQLite.
+ * Replaces JWT-based TokenService with revocable, trackable sessions.
+ */
+
+import type { Database } from 'bun:sqlite';
+import { createHash, randomBytes } from 'node:crypto';
+import { injectable } from '@brika/di';
+import { getAuthConfig } from '../config';
+import { ROLE_SCOPES } from '../roles';
+import { Role, Scope, type Session, type SessionRecord } from '../types';
+
+interface SessionRow {
+  id: string;
+  user_id: string;
+  token_hash: string;
+  ip: string | null;
+  user_agent: string | null;
+  created_at: number;
+  last_seen_at: number;
+  expires_at: number;
+  revoked_at: number | null;
+}
+
+interface SessionWithUserRow extends SessionRow {
+  email: string;
+  name: string;
+  role: string;
+  scopes: string | null;
+}
+
+function parseScopes(raw: string | null): Scope[] {
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    const valid = new Set<string>(Object.values(Scope));
+    return parsed.filter((s: string) => valid.has(s)) as Scope[];
+  } catch {
+    return [];
+  }
+}
+
+/** SHA-256 hash of a raw token */
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+/** Generate a cryptographically random session token */
+function generateToken(): string {
+  return randomBytes(32).toString('hex');
+}
+
+function generateId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+function toSessionRecord(row: SessionRow): SessionRecord {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    tokenHash: row.token_hash,
+    ip: row.ip,
+    userAgent: row.user_agent,
+    createdAt: row.created_at,
+    lastSeenAt: row.last_seen_at,
+    expiresAt: row.expires_at,
+    revokedAt: row.revoked_at,
+  };
+}
+
+@injectable()
+export class SessionService {
+  private readonly sessionTTL: number;
+
+  constructor(
+    private readonly db: Database,
+    sessionTTL?: number
+  ) {
+    this.sessionTTL = sessionTTL ?? getAuthConfig().session.ttl;
+  }
+
+  /**
+   * Create a new session. Returns the raw token (only time it's available).
+   * Automatically revokes the oldest sessions if the per-user limit is exceeded.
+   */
+  createSession(userId: string, ip?: string, userAgent?: string): string {
+    const id = generateId();
+    const token = generateToken();
+    const tokenHash = hashToken(token);
+    const now = Date.now();
+    const expiresAt = now + this.sessionTTL * 1000;
+
+    this.db
+      .query(
+        `INSERT INTO sessions (id, user_id, token_hash, ip, user_agent, created_at, last_seen_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(id, userId, tokenHash, ip ?? null, userAgent ?? null, now, now, expiresAt);
+
+    // Enforce per-user session limit — revoke oldest sessions beyond the cap
+    this.#enforceSessionLimit(userId, now);
+
+    return token;
+  }
+
+  #enforceSessionLimit(userId: string, now: number): void {
+    const { maxPerUser } = getAuthConfig().session;
+    const activeSessions = this.db
+      .query<
+        {
+          id: string;
+        },
+        [string, number]
+      >(
+        `SELECT id FROM sessions
+         WHERE user_id = ? AND revoked_at IS NULL AND expires_at > ?
+         ORDER BY last_seen_at DESC`
+      )
+      .all(userId, now);
+
+    if (activeSessions.length <= maxPerUser) {
+      return;
+    }
+
+    // Revoke all sessions beyond the limit (oldest first, they're at the end)
+    const toRevoke = activeSessions.slice(maxPerUser);
+    for (const session of toRevoke) {
+      this.db.query(`UPDATE sessions SET revoked_at = ? WHERE id = ?`).run(now, session.id);
+    }
+  }
+
+  /**
+   * Validate a session token.
+   * Returns the session if valid, null if expired/revoked/unknown.
+   * Updates last_seen_at and ip on each successful validation (sliding expiration).
+   */
+  validateSession(token: string, ip?: string): Session | null {
+    const tokenHash = hashToken(token);
+    const now = Date.now();
+
+    const row = this.db
+      .query<SessionWithUserRow, [string]>(
+        `SELECT s.*, u.email, u.name, u.role, u.scopes
+         FROM sessions s
+         JOIN users u ON u.id = s.user_id
+         WHERE s.token_hash = ? AND u.is_active = 1`
+      )
+      .get(tokenHash);
+
+    if (!row) {
+      return null;
+    }
+    if (row.revoked_at !== null) {
+      return null;
+    }
+    if (row.expires_at < now) {
+      return null;
+    }
+
+    // Sliding expiration: extend session + update last_seen_at & ip
+    const newExpiresAt = now + this.sessionTTL * 1000;
+    this.db
+      .query(
+        `UPDATE sessions SET last_seen_at = ?, expires_at = ?, ip = COALESCE(?, ip) WHERE id = ?`
+      )
+      .run(now, newExpiresAt, ip ?? null, row.id);
+
+    const role = (row.role as Role) ?? Role.USER;
+
+    // Admins always get full admin scopes; others use their explicit allow-list
+    const scopes: Scope[] = role === Role.ADMIN ? ROLE_SCOPES[Role.ADMIN] : parseScopes(row.scopes);
+
+    return {
+      id: row.id,
+      userId: row.user_id,
+      userEmail: row.email,
+      userName: row.name,
+      userRole: role,
+      scopes,
+    };
+  }
+
+  /**
+   * Revoke a specific session by ID.
+   */
+  revokeSession(sessionId: string): void {
+    const now = Date.now();
+    this.db
+      .query(`UPDATE sessions SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL`)
+      .run(now, sessionId);
+  }
+
+  /**
+   * Revoke all sessions for a user.
+   */
+  revokeAllUserSessions(userId: string): void {
+    const now = Date.now();
+    this.db
+      .query(`UPDATE sessions SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL`)
+      .run(now, userId);
+  }
+
+  /**
+   * List active (non-revoked, non-expired) sessions for a user.
+   */
+  listUserSessions(userId: string): SessionRecord[] {
+    const now = Date.now();
+    const rows = this.db
+      .query<SessionRow, [string, number]>(
+        `SELECT * FROM sessions
+         WHERE user_id = ? AND revoked_at IS NULL AND expires_at > ?
+         ORDER BY last_seen_at DESC`
+      )
+      .all(userId, now);
+
+    return rows.map(toSessionRecord);
+  }
+
+  /**
+   * Clean up expired and revoked sessions older than 30 days.
+   */
+  cleanExpiredSessions(): number {
+    const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+    const result = this.db
+      .query(
+        `DELETE FROM sessions WHERE (expires_at < ? OR revoked_at IS NOT NULL) AND created_at < ?`
+      )
+      .run(cutoff, cutoff);
+
+    return result.changes;
+  }
+
+  /**
+   * Get session TTL in seconds.
+   */
+  getSessionTTL(): number {
+    return this.sessionTTL;
+  }
+}

package/src/services/UserService.ts

@@ -0,0 +1,245 @@
+/**
+ * @brika/auth - UserService
+ * Pure SQLite-backed user CRUD operations.
+ */
+
+import type { Database } from 'bun:sqlite';
+import { photon } from '@brika/photon';
+import bcryptjs from 'bcryptjs';
+import { ROLE_SCOPES } from '../constants';
+import { validatePassword } from '../schemas';
+import { Role, Scope, type User } from '../types';
+
+const AVATAR_SIZE = 256;
+
+interface UserRow {
+  id: string;
+  email: string;
+  name: string;
+  role: Role;
+  avatar_hash: string | null;
+  is_active: number;
+  scopes: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function parseScopes(raw: string | null): Scope[] {
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    const valid = new Set<string>(Object.values(Scope));
+    return parsed.filter((s: string) => valid.has(s));
+  } catch {
+    return [];
+  }
+}
+
+function toUser(row: UserRow): User {
+  return {
+    id: row.id,
+    email: row.email,
+    name: row.name,
+    role: row.role,
+    avatarHash: row.avatar_hash,
+    isActive: row.is_active === 1,
+    scopes: parseScopes(row.scopes),
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  };
+}
+
+/** Center-crop to square, compress as webp. */
+export function processAvatar(input: Buffer): Buffer {
+  return photon(input)
+    .resize(AVATAR_SIZE, AVATAR_SIZE, {
+      fit: 'cover',
+    })
+    .webp()
+    .toBuffer();
+}
+
+// ─── Service ─────────────────────────────────────────────────────────────────
+
+export class UserService {
+  constructor(private readonly db: Database) {}
+
+  getUser(id: string): User | null {
+    const row = this.db.prepare('SELECT * FROM users WHERE id = ?').get(id) as UserRow | undefined;
+    return row ? toUser(row) : null;
+  }
+
+  getUserByEmail(email: string): User | null {
+    const row = this.db.prepare('SELECT * FROM users WHERE email = ?').get(email.toLowerCase()) as
+      | UserRow
+      | undefined;
+    return row ? toUser(row) : null;
+  }
+
+  listUsers(): User[] {
+    const rows = this.db.prepare('SELECT * FROM users ORDER BY created_at DESC').all() as UserRow[];
+    return rows.map(toUser);
+  }
+
+  createUser(email: string, name: string, role: Role): User {
+    const id = crypto.randomUUID();
+    const now = Date.now();
+    const scopes = ROLE_SCOPES[role] ?? [];
+
+    this.db
+      .prepare(
+        `INSERT INTO users (id, email, name, role, scopes, is_active, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, 1, ?, ?)`
+      )
+      .run(id, email.toLowerCase(), name, role, JSON.stringify(scopes), now, now);
+
+    return {
+      id,
+      email: email.toLowerCase(),
+      name,
+      role,
+      avatarHash: null,
+      createdAt: new Date(now),
+      updatedAt: new Date(now),
+      isActive: true,
+      scopes,
+    };
+  }
+
+  updateUser(
+    id: string,
+    updates: {
+      name?: string;
+      role?: Role;
+      isActive?: boolean;
+      scopes?: Scope[];
+    }
+  ): User {
+    const user = this.getUser(id);
+    if (!user) {
+      throw new Error('User not found');
+    }
+
+    const now = Date.now();
+    const name = updates.name ?? user.name;
+
+    const sets: string[] = ['name = ?', 'updated_at = ?'];
+    const params: (string | number)[] = [name, now];
+
+    if (updates.role !== undefined) {
+      sets.push('role = ?');
+      params.push(updates.role);
+    }
+    let isActive: number | undefined;
+    if (updates.isActive !== undefined) {
+      isActive = updates.isActive ? 1 : 0;
+    }
+    if (isActive !== undefined) {
+      sets.push('is_active = ?');
+      params.push(isActive);
+    }
+    if (updates.scopes !== undefined) {
+      sets.push('scopes = ?');
+      params.push(JSON.stringify(updates.scopes));
+    }
+
+    params.push(id);
+    this.db.prepare(`UPDATE users SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+
+    const updated = this.getUser(id);
+    if (!updated) {
+      throw new Error('User not found after update');
+    }
+    return updated;
+  }
+
+  /** Set avatar from raw image data (processed to webp). Returns content hash for cache busting. */
+  setAvatar(userId: string, imageData: Buffer): string {
+    const processed = processAvatar(imageData);
+    const hash = Bun.hash(processed).toString(36).slice(0, 8);
+    this.db
+      .prepare(
+        'UPDATE users SET avatar_data = ?, avatar_mime = ?, avatar_hash = ?, updated_at = ? WHERE id = ?'
+      )
+      .run(processed, 'image/webp', hash, Date.now(), userId);
+    return hash;
+  }
+
+  /** Remove avatar */
+  removeAvatar(userId: string): void {
+    this.db
+      .prepare(
+        'UPDATE users SET avatar_data = NULL, avatar_mime = NULL, avatar_hash = NULL, updated_at = ? WHERE id = ?'
+      )
+      .run(Date.now(), userId);
+  }
+
+  /** Get raw avatar data for serving */
+  getAvatarData(userId: string): {
+    data: Buffer;
+    mimeType: string;
+  } | null {
+    const row = this.db
+      .prepare('SELECT avatar_data, avatar_mime FROM users WHERE id = ?')
+      .get(userId) as
+      | {
+          avatar_data: Buffer | null;
+          avatar_mime: string | null;
+        }
+      | undefined;
+    if (!row?.avatar_data || !row.avatar_mime) {
+      return null;
+    }
+    return {
+      data: row.avatar_data,
+      mimeType: row.avatar_mime,
+    };
+  }
+
+  deleteUser(email: string): void {
+    const user = this.getUserByEmail(email);
+    if (!user) {
+      throw new Error('User not found');
+    }
+    if (user.role === Role.ADMIN) {
+      throw new Error('Cannot delete admin user');
+    }
+    this.db.prepare('DELETE FROM users WHERE email = ?').run(email.toLowerCase());
+  }
+
+  async setPassword(userId: string, password: string): Promise<void> {
+    const user = this.getUser(userId);
+    if (!user) {
+      throw new Error('User not found');
+    }
+    const error = validatePassword(password);
+    if (error) {
+      throw new Error(error);
+    }
+    const hash = await bcryptjs.hash(password, 12);
+    this.db
+      .prepare('UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?')
+      .run(hash, Date.now(), userId);
+  }
+
+  async verifyPassword(userId: string, password: string): Promise<boolean> {
+    const row = this.db.prepare('SELECT password_hash FROM users WHERE id = ?').get(userId) as
+      | {
+          password_hash: string | null;
+        }
+      | undefined;
+    if (!row?.password_hash) {
+      return false;
+    }
+    return await bcryptjs.compare(password, row.password_hash);
+  }
+
+  hasAdmin(): boolean {
+    return this.db.prepare("SELECT 1 FROM users WHERE role = 'admin' LIMIT 1").get() !== null;
+  }
+}

package/src/setup.ts

@@ -0,0 +1,99 @@
+/**
+ * @brika/auth - Setup
+ * Opens SQLite database, creates schema, registers services in DI.
+ */
+
+import { Database } from 'bun:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { container } from '@brika/di';
+import { type AuthConfig, initAuthConfig } from './config';
+import { AuthService } from './services/AuthService';
+import { ScopeService } from './services/ScopeService';
+import { SessionService } from './services/SessionService';
+import { UserService } from './services/UserService';
+
+/**
+ * Open the SQLite database and create tables if needed.
+ */
+export function openAuthDatabase(path: string): Database {
+  if (path !== ':memory:') {
+    mkdirSync(dirname(path), {
+      recursive: true,
+      mode: 0o700,
+    });
+  }
+
+  const db = new Database(path, {
+    strict: true,
+  });
+
+  // Restrict database file to owner-only access (contains password hashes and session data)
+  if (path !== ':memory:') {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      /* may fail on some platforms */
+    }
+  }
+  db.run('PRAGMA journal_mode = WAL');
+  db.run('PRAGMA synchronous = NORMAL');
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      email TEXT UNIQUE NOT NULL,
+      password_hash TEXT,
+      name TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'user',
+      is_active INTEGER DEFAULT 1,
+      avatar_data BLOB,
+      avatar_mime TEXT,
+      avatar_hash TEXT,
+      scopes TEXT DEFAULT '[]',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      token_hash TEXT UNIQUE NOT NULL,
+      ip TEXT,
+      user_agent TEXT,
+      created_at INTEGER NOT NULL,
+      last_seen_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      revoked_at INTEGER,
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    )
+  `);
+
+  db.run('CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)');
+  db.run('CREATE INDEX IF NOT EXISTS idx_sessions_token_hash ON sessions(token_hash)');
+  db.run('CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id)');
+
+  return db;
+}
+
+/**
+ * Register all auth services in the DI container.
+ * Must be called after `openAuthDatabase`.
+ */
+export function setupAuthServices(db: Database, config?: AuthConfig): void {
+  const resolved = initAuthConfig(config);
+  container.register(SessionService, {
+    useValue: new SessionService(db, resolved.session.ttl),
+  });
+  container.register(UserService, {
+    useValue: new UserService(db),
+  });
+  container.register(ScopeService, {
+    useClass: ScopeService,
+  });
+  container.register(AuthService, {
+    useClass: AuthService,
+  });
+}

package/src/tanstack/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @brika/auth/tanstack
+ * TanStack Router integration for protected routes
+ */
+
+export type {
+  ExtractParams,
+  NormalizeParam,
+  ParamsArg,
+  ProtectedRouteDefinition,
+  ProtectedRouteResult,
+  ProtectedRoutesOptions,
+  ProtectedRouteWithChildren,
+} from './routeBuilder';
+export { createProtectedRoute, createProtectedRoutes, resolvePath } from './routeBuilder';