refactor(database): move db into typescript

- Implemented githubTokensDb for managing GitHub tokens with CRUD operations. - Created otificationPreferencesDb to handle user notification preferences. - Added projectsDb for project path management and related operations. - Introduced pushSubscriptionsDb for managing browser push subscriptions. - Developed scanStateDb to track the last scanned timestamp. - Established sessionsDb for session management with CRUD functionalities. - Created userDb for user management, including authentication and onboarding. - Implemented apidKeysDb for storing and managing VAPID keys. feat(database): define schema for new database tables - Added SQL schema definitions for users, API keys, user credentials, notification preferences, VAPID keys, push subscriptions, projects, sessions, scan state, and app configuration. - Included necessary indexes for performance optimization. refactor(shared): enhance type definitions and utility functions - Updated shared types and interfaces for improved clarity and consistency. - Added new types for credential management and provider-specific operations. - Refined utility functions for better error handling and message normalization.
2026-05-28 23:15:33 +08:00 · 2026-04-23 16:59:45 +03:00
parent 2e326214e1
commit 7b75ed0b72
18 changed files with 1879 additions and 42 deletions
--- a/server/modules/database/repositories/api-keys.ts
+++ b/server/modules/database/repositories/api-keys.ts
@@ -0,0 +1,119 @@
+/**
+ * API keys repository.
+ *
+ * Manages API keys used for external/programmatic access to the backend.
+ * Keys are prefixed with `ck_` and tied to a user via foreign key.
+ */
+
+import crypto from 'crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type ApiKeyRow = {
+  id: number;
+  key_name: string;
+  api_key: string;
+  created_at: string;
+  last_used: string | null;
+  is_active: number;
+};
+
+type CreateApiKeyResult = {
+  id: number | bigint;
+  keyName: string;
+  apiKey: string;
+};
+
+type ValidatedApiKeyUser = {
+  id: number;
+  username: string;
+  api_key_id: number;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Generates a cryptographically random API key with the `ck_` prefix. */
+function generateApiKey(): string {
+  return 'ck_' + crypto.randomBytes(32).toString('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const apiKeysDb = {
+  generateApiKey,
+
+  /** Creates a new API key for the given user and returns it for one-time display. */
+  createApiKey(userId: number, keyName: string): CreateApiKeyResult {
+    const db = getConnection();
+    const apiKey = generateApiKey();
+    const result = db
+      .prepare(
+        'INSERT INTO api_keys (user_id, key_name, api_key) VALUES (?, ?, ?)'
+      )
+      .run(userId, keyName, apiKey);
+    return { id: result.lastInsertRowid, keyName, apiKey };
+  },
+
+  /** Lists all API keys for a user, most recent first. */
+  getApiKeys(userId: number): ApiKeyRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, key_name, api_key, created_at, last_used, is_active FROM api_keys WHERE user_id = ? ORDER BY created_at DESC'
+      )
+      .all(userId) as ApiKeyRow[];
+  },
+
+  /**
+   * Validates an API key and resolves the owning user.
+   * If the key is valid, its `last_used` timestamp is updated as a side effect.
+   * Returns undefined when the key is invalid or the user is inactive.
+   */
+  validateApiKey(apiKey: string): ValidatedApiKeyUser | undefined {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT u.id, u.username, ak.id as api_key_id
+         FROM api_keys ak
+         JOIN users u ON ak.user_id = u.id
+         WHERE ak.api_key = ? AND ak.is_active = 1 AND u.is_active = 1`
+      )
+      .get(apiKey) as ValidatedApiKeyUser | undefined;
+
+    if (row) {
+      db.prepare(
+        'UPDATE api_keys SET last_used = CURRENT_TIMESTAMP WHERE id = ?'
+      ).run(row.api_key_id);
+    }
+
+    return row;
+  },
+
+  /** Permanently removes an API key. Returns true if a row was deleted. */
+  deleteApiKey(userId: number, apiKeyId: number): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare('DELETE FROM api_keys WHERE id = ? AND user_id = ?')
+      .run(apiKeyId, userId);
+    return result.changes > 0;
+  },
+
+  /** Enables or disables an API key without deleting it. */
+  toggleApiKey(
+    userId: number,
+    apiKeyId: number,
+    isActive: boolean
+  ): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'UPDATE api_keys SET is_active = ? WHERE id = ? AND user_id = ?'
+      )
+      .run(isActive ? 1 : 0, apiKeyId, userId);
+    return result.changes > 0;
+  },
+};
--- a/server/modules/database/repositories/app-config.ts
+++ b/server/modules/database/repositories/app-config.ts
@@ -0,0 +1,53 @@
+/**
+ * App config repository.
+ *
+ * Key-value store for application-level configuration that persists
+ * across restarts (JWT secret, feature flags, etc.). Values are always
+ * stored as strings; callers handle parsing.
+ */
+
+import crypto from 'crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const appConfigDb = {
+  /** Returns the stored value for a config key, or null if missing. */
+  get(key: string): string | null {
+    try {
+      const db = getConnection();
+      const row = db
+        .prepare('SELECT value FROM app_config WHERE key = ?')
+        .get(key) as { value: string } | undefined;
+      return row?.value ?? null;
+    } catch {
+      // Swallow errors so early-startup reads (e.g. JWT secret) do not crash.
+      return null;
+    }
+  },
+
+  /** Inserts or updates a config key (upsert). */
+  set(key: string, value: string): void {
+    const db = getConnection();
+    db.prepare(
+      'INSERT INTO app_config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value'
+    ).run(key, value);
+  },
+
+  /**
+   * Returns the JWT signing secret, generating and persisting one
+   * if it does not already exist. This ensures the secret survives
+   * server restarts while being created automatically on first boot.
+   */
+  getOrCreateJwtSecret(): string {
+    let secret = appConfigDb.get('jwt_secret');
+    if (!secret) {
+      secret = crypto.randomBytes(64).toString('hex');
+      appConfigDb.set('jwt_secret', secret);
+    }
+    return secret;
+  },
+};
--- a/server/modules/database/repositories/credentials.ts
+++ b/server/modules/database/repositories/credentials.ts
@@ -0,0 +1,106 @@
+/**
+ * User credentials repository.
+ *
+ * Manages external service tokens (GitHub, GitLab, Bitbucket, etc.)
+ * stored per-user. Each credential has a type discriminator so multiple
+ * credential kinds can coexist in the same table.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+import type {
+  CreateCredentialResult,
+  CredentialPublicRow,
+} from '@/shared/types.js';
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const credentialsDb = {
+  /** Stores a new credential and returns a safe (no raw value) result. */
+  createCredential(
+    userId: number,
+    credentialName: string,
+    credentialType: string,
+    credentialValue: string,
+    description: string | null = null
+  ): CreateCredentialResult {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'INSERT INTO user_credentials (user_id, credential_name, credential_type, credential_value, description) VALUES (?, ?, ?, ?, ?)'
+      )
+      .run(userId, credentialName, credentialType, credentialValue, description);
+    return {
+      id: result.lastInsertRowid,
+      credentialName,
+      credentialType,
+    };
+  },
+
+  /**
+   * Lists credentials for a user (excluding raw values).
+   * Optionally filters by credential type (e.g. 'github_token').
+   */
+  getCredentials(
+    userId: number,
+    credentialType: string | null = null
+  ): CredentialPublicRow[] {
+    const db = getConnection();
+
+    if (credentialType) {
+      return db
+        .prepare(
+          'SELECT id, credential_name, credential_type, description, created_at, is_active FROM user_credentials WHERE user_id = ? AND credential_type = ? ORDER BY created_at DESC'
+        )
+        .all(userId, credentialType) as CredentialPublicRow[];
+    }
+
+    return db
+      .prepare(
+        'SELECT id, credential_name, credential_type, description, created_at, is_active FROM user_credentials WHERE user_id = ? ORDER BY created_at DESC'
+      )
+      .all(userId) as CredentialPublicRow[];
+  },
+
+  /**
+   * Returns the raw credential value for the most recent active
+   * credential of the given type, or null if none exists.
+   */
+  getActiveCredential(
+    userId: number,
+    credentialType: string
+  ): string | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT credential_value FROM user_credentials WHERE user_id = ? AND credential_type = ? AND is_active = 1 ORDER BY created_at DESC LIMIT 1'
+      )
+      .get(userId, credentialType) as { credential_value: string } | undefined;
+    return row?.credential_value ?? null;
+  },
+
+  /** Permanently removes a credential. Returns true if a row was deleted. */
+  deleteCredential(userId: number, credentialId: number): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare('DELETE FROM user_credentials WHERE id = ? AND user_id = ?')
+      .run(credentialId, userId);
+    return result.changes > 0;
+  },
+
+  /** Enables or disables a credential without deleting it. */
+  toggleCredential(
+    userId: number,
+    credentialId: number,
+    isActive: boolean
+  ): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'UPDATE user_credentials SET is_active = ? WHERE id = ? AND user_id = ?'
+      )
+      .run(isActive ? 1 : 0, credentialId, userId);
+    return result.changes > 0;
+  },
+};
--- a/server/modules/database/repositories/github-tokens.ts
+++ b/server/modules/database/repositories/github-tokens.ts
@@ -0,0 +1,100 @@
+/**
+ * GitHub tokens repository.
+ *
+ * Backward-compatible helper layer over generic credentials storage.
+ * Tokens are stored in `user_credentials` with `credential_type = 'github_token'`.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+import { credentialsDb } from '@/modules/database/repositories/credentials.js';
+import type {
+  CredentialPublicRow,
+  CreateCredentialResult,
+} from '@/shared/types.js';
+
+const GITHUB_TOKEN_TYPE = 'github_token';
+
+type CredentialRow = {
+  id: number;
+  user_id: number;
+  credential_name: string;
+  credential_type: string;
+  credential_value: string;
+  description: string | null;
+  created_at: string;
+  is_active: number;
+};
+
+type GithubTokenLookup = CredentialRow & {
+  github_token: string;
+};
+
+export const githubTokensDb = {
+  /** Creates a GitHub token credential entry. */
+  createGithubToken(
+    userId: number,
+    tokenName: string,
+    githubToken: string,
+    description: string | null = null
+  ): CreateCredentialResult {
+    return credentialsDb.createCredential(
+      userId,
+      tokenName,
+      GITHUB_TOKEN_TYPE,
+      githubToken,
+      description
+    );
+  },
+
+  /** Returns all GitHub tokens (safe shape: no credential value). */
+  getGithubTokens(userId: number): CredentialPublicRow[] {
+    return credentialsDb.getCredentials(userId, GITHUB_TOKEN_TYPE);
+  },
+
+  /** Returns the most recent active GitHub token value for a user. */
+  getActiveGithubToken(userId: number): string | null {
+    return credentialsDb.getActiveCredential(userId, GITHUB_TOKEN_TYPE);
+  },
+
+  /**
+   * Returns a specific active GitHub token row by id/user, including
+   * a `github_token` compatibility field.
+   */
+  getGithubTokenById(userId: number, tokenId: number): GithubTokenLookup | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT *
+         FROM user_credentials
+         WHERE id = ? AND user_id = ? AND credential_type = ? AND is_active = 1`
+      )
+      .get(tokenId, userId, GITHUB_TOKEN_TYPE) as CredentialRow | undefined;
+
+    if (!row) return null;
+
+    return {
+      ...row,
+      github_token: row.credential_value,
+    };
+  },
+
+  /** Updates active state for a GitHub token. */
+  updateGithubToken(
+    userId: number,
+    tokenId: number,
+    isActive: boolean
+  ): boolean {
+    return credentialsDb.toggleCredential(userId, tokenId, isActive);
+  },
+
+  /** Deletes a GitHub token. */
+  deleteGithubToken(userId: number, tokenId: number): boolean {
+    return credentialsDb.deleteCredential(userId, tokenId);
+  },
+
+  // Legacy alias used by existing routes
+  toggleGithubToken(userId: number, tokenId: number, isActive: boolean): boolean {
+    return githubTokensDb.updateGithubToken(userId, tokenId, isActive);
+  },
+};
+
--- a/server/modules/database/repositories/notification-preferences.ts
+++ b/server/modules/database/repositories/notification-preferences.ts
@@ -0,0 +1,103 @@
+/**
+ * Notification preferences repository.
+ *
+ * Stores per-user notification channel/event preferences as JSON.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type NotificationPreferences = {
+  channels: {
+    inApp: boolean;
+    webPush: boolean;
+  };
+  events: {
+    actionRequired: boolean;
+    stop: boolean;
+    error: boolean;
+  };
+};
+
+const DEFAULT_NOTIFICATION_PREFERENCES: NotificationPreferences = {
+  channels: {
+    inApp: false,
+    webPush: false,
+  },
+  events: {
+    actionRequired: true,
+    stop: true,
+    error: true,
+  },
+};
+
+function normalizeNotificationPreferences(value: unknown): NotificationPreferences {
+  const source = value && typeof value === 'object' ? (value as Record<string, any>) : {};
+
+  return {
+    channels: {
+      inApp: source.channels?.inApp === true,
+      webPush: source.channels?.webPush === true,
+    },
+    events: {
+      actionRequired: source.events?.actionRequired !== false,
+      stop: source.events?.stop !== false,
+      error: source.events?.error !== false,
+    },
+  };
+}
+
+export const notificationPreferencesDb = {
+  /** Returns the normalized preferences for a user, creating defaults on first read. */
+  getNotificationPreferences(userId: number): NotificationPreferences {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?'
+      )
+      .get(userId) as { preferences_json: string } | undefined;
+
+    if (!row) {
+      const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
+      db.prepare(
+        'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
+      ).run(userId, JSON.stringify(defaults));
+      return defaults;
+    }
+
+    let parsed: unknown = DEFAULT_NOTIFICATION_PREFERENCES;
+    try {
+      parsed = JSON.parse(row.preferences_json);
+    } catch {
+      parsed = DEFAULT_NOTIFICATION_PREFERENCES;
+    }
+    return normalizeNotificationPreferences(parsed);
+  },
+
+  /** Upserts normalized preferences for a user and returns the stored value. */
+  updateNotificationPreferences(
+    userId: number,
+    preferences: unknown
+  ): NotificationPreferences {
+    const normalized = normalizeNotificationPreferences(preferences);
+    const db = getConnection();
+
+    db.prepare(
+      `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
+       VALUES (?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(user_id) DO UPDATE SET
+         preferences_json = excluded.preferences_json,
+         updated_at = CURRENT_TIMESTAMP`
+    ).run(userId, JSON.stringify(normalized));
+
+    return normalized;
+  },
+
+  // Legacy aliases used by existing services/routes
+  getPreferences(userId: number): NotificationPreferences {
+    return notificationPreferencesDb.getNotificationPreferences(userId);
+  },
+  updatePreferences(userId: number, preferences: unknown): NotificationPreferences {
+    return notificationPreferencesDb.updateNotificationPreferences(userId, preferences);
+  },
+};
+
--- a/server/modules/database/repositories/projects.db.ts
+++ b/server/modules/database/repositories/projects.db.ts
@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type ProjectRow = {
+  project_id: string;
+  project_path: string;
+  custom_project_name: string | null;
+  isStarred: number;
+  isArchived: number;
+};
+
+export const projectsDb = {
+    createProjectPath(projectPath: string, customProjectName: string | null = null): void {
+        const db = getConnection();
+        db.prepare(`
+            INSERT INTO projects (project_id, project_path, custom_project_name)
+            VALUES (?, ?, ?)
+            ON CONFLICT(project_path) DO UPDATE SET
+              custom_project_name = CASE
+                WHEN projects.custom_project_name IS NULL OR projects.custom_project_name = ''
+                THEN excluded.custom_project_name
+                ELSE projects.custom_project_name
+              END
+        `).run(randomUUID(), projectPath, customProjectName);
+    },
+
+    getProjectPath(projectPath: string): ProjectRow | null {
+        const db = getConnection();
+        const row = db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE project_path = ?
+        `).get(projectPath) as ProjectRow | undefined;
+
+        return row ?? null;
+    },
+
+    getProjectById(projectId: string): ProjectRow | null {
+        const db = getConnection();
+        const row = db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE project_id = ?
+        `).get(projectId) as ProjectRow | undefined;
+
+        return row ?? null;
+    },
+
+    getProjectPaths(): ProjectRow[] {
+        const db = getConnection();
+        return db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+        `).all() as ProjectRow[];
+    },
+
+    getCustomProjectName(projectPath: string): string | null {
+        const db = getConnection();
+        const row = db.prepare(`
+            SELECT custom_project_name
+            FROM projects
+            WHERE project_path = ?
+        `).get(projectPath) as Pick<ProjectRow, 'custom_project_name'> | undefined;
+
+        return row?.custom_project_name ?? null;
+    },
+
+    updateCustomProjectName(projectPath: string, customProjectName: string | null): void {
+        const db = getConnection();
+        db.prepare(`
+            INSERT INTO projects (project_id, project_path, custom_project_name)
+            VALUES (?, ?, ?)
+            ON CONFLICT(project_path) DO UPDATE SET custom_project_name = excluded.custom_project_name
+        `).run(randomUUID(), projectPath, customProjectName);
+    },
+
+    updateCustomProjectNameById(projectId: string, customProjectName: string | null): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET custom_project_name = ?
+            WHERE project_id = ?
+        `).run(customProjectName, projectId);
+    },
+
+    updateProjectIsStarred(projectPath: string, isStarred: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isStarred = ?
+            WHERE project_path = ?
+        `).run(isStarred ? 1 : 0, projectPath);
+    },
+
+    updateProjectIsStarredById(projectId: string, isStarred: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isStarred = ?
+            WHERE project_id = ?
+        `).run(isStarred ? 1 : 0, projectId);
+    },
+
+    updateProjectIsArchived(projectPath: string, isArchived: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isArchived = ?
+            WHERE project_path = ?
+        `).run(isArchived ? 1 : 0, projectPath);
+    },
+
+    updateProjectIsArchivedById(projectId: string, isArchived: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isArchived = ?
+            WHERE project_id = ?
+        `).run(isArchived ? 1 : 0, projectId);
+    },
+
+    deleteProjectPath(projectPath: string): void {
+        const db = getConnection();
+        db.prepare(`
+            DELETE FROM projects
+            WHERE project_path = ?
+        `).run(projectPath);
+    },
+
+    deleteProjectById(projectId: string): void {
+        const db = getConnection();
+        db.prepare(`
+            DELETE FROM projects
+            WHERE project_id = ?
+        `).run(projectId);
+    },
+};
--- a/server/modules/database/repositories/push-subscriptions.ts
+++ b/server/modules/database/repositories/push-subscriptions.ts
@@ -0,0 +1,80 @@
+/**
+ * Push subscriptions repository.
+ *
+ * Persists browser push subscription endpoints and keys per user.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type PushSubscriptionLookupRow = {
+  endpoint: string;
+  keys_p256dh: string;
+  keys_auth: string;
+};
+
+export const pushSubscriptionsDb = {
+  /** Upserts a push subscription endpoint for a user. */
+  createPushSubscription(
+    userId: number,
+    endpoint: string,
+    keysP256dh: string,
+    keysAuth: string
+  ): void {
+    const db = getConnection();
+    db.prepare(
+      `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(endpoint) DO UPDATE SET
+         user_id = excluded.user_id,
+         keys_p256dh = excluded.keys_p256dh,
+         keys_auth = excluded.keys_auth`
+    ).run(userId, endpoint, keysP256dh, keysAuth);
+  },
+
+  /** Returns all subscriptions for a user. */
+  getPushSubscriptions(userId: number): PushSubscriptionLookupRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?'
+      )
+      .all(userId) as PushSubscriptionLookupRow[];
+  },
+
+  /** Deletes one subscription by endpoint. */
+  deletePushSubscription(endpoint: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
+  },
+
+  /** Deletes all subscriptions for a user. */
+  deletePushSubscriptionsForUser(userId: number): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
+  },
+
+  // Legacy aliases used by existing services/routes
+  saveSubscription(
+    userId: number,
+    endpoint: string,
+    keysP256dh: string,
+    keysAuth: string
+  ): void {
+    pushSubscriptionsDb.createPushSubscription(
+      userId,
+      endpoint,
+      keysP256dh,
+      keysAuth
+    );
+  },
+  getSubscriptions(userId: number): PushSubscriptionLookupRow[] {
+    return pushSubscriptionsDb.getPushSubscriptions(userId);
+  },
+  removeSubscription(endpoint: string): void {
+    pushSubscriptionsDb.deletePushSubscription(endpoint);
+  },
+  removeAllForUser(userId: number): void {
+    pushSubscriptionsDb.deletePushSubscriptionsForUser(userId);
+  },
+};
+
--- a/server/modules/database/repositories/scan-state.db.ts
+++ b/server/modules/database/repositories/scan-state.db.ts
@@ -0,0 +1,41 @@
+import { getConnection } from '@/modules/database/connection.js';
+
+type ScanStateRow = {
+  last_scanned_at: string;
+};
+
+export const scanStateDb = {
+    getLastScannedAt() {
+        const db = getConnection();
+
+        const row = db
+            .prepare(`SELECT last_scanned_at FROM scan_state WHERE id = 1`)
+            .get() as ScanStateRow;
+
+        if (!row) {
+            return null; // Before any scan, the row is undefined.
+        }
+
+        let lastScannedDate: Date | null = null;
+        const lastScannedStr = row.last_scanned_at;
+
+        if (lastScannedStr) {
+            // SQLite CURRENT_TIMESTAMP returns UTC in "YYYY-MM-DD HH:MM:SS" format.
+            // Replace space with 'T' and append 'Z' to parse reliably in JS across all platforms.
+            lastScannedDate = new Date(lastScannedStr.replace(' ', 'T') + 'Z');
+        }
+
+        return lastScannedDate;
+    },
+
+    updateLastScannedAt() {
+        const db = getConnection();
+
+        db.prepare(`
+            INSERT INTO scan_state (id, last_scanned_at)
+            VALUES (1, CURRENT_TIMESTAMP)
+            ON CONFLICT (id)
+            DO UPDATE SET last_scanned_at = CURRENT_TIMESTAMP
+        `).run();
+    }
+};
--- a/server/modules/database/repositories/sessions.db.ts
+++ b/server/modules/database/repositories/sessions.db.ts
@@ -0,0 +1,192 @@
+import path from 'node:path';
+
+import { getConnection } from '@/modules/database/connection.js';
+import { projectsDb } from '@/modules/database/repositories/projects.db.js';
+
+type SessionNameLookupRow = {
+  session_id: string;
+  custom_name: string;
+};
+
+type SessionRow = {
+  session_id: string;
+  provider: string;
+  project_path: string | null;
+  jsonl_path: string | null;
+  custom_name: string | null;
+  created_at: string;
+  updated_at: string;
+};
+
+type SessionMetadataLookupRow = Pick<
+  SessionRow,
+  'session_id' | 'provider' | 'project_path' | 'jsonl_path' | 'custom_name' | 'created_at' | 'updated_at'
+>;
+
+function normalizeTimestamp(value?: string): string | null {
+  if (!value) return null;
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return null;
+  }
+
+  return parsed.toISOString();
+}
+
+function normalizeCodexProjectPath(projectPath: string): string {
+  const trimmedPath = projectPath.trim();
+  if (!trimmedPath) {
+    return projectPath;
+  }
+
+  if (process.platform !== 'win32') {
+    return path.normalize(trimmedPath);
+  }
+
+  let strippedPath = trimmedPath;
+  if (strippedPath.startsWith('\\\\?\\UNC\\')) {
+    strippedPath = `\\\\${strippedPath.slice('\\\\?\\UNC\\'.length)}`;
+  } else if (strippedPath.startsWith('\\\\?\\')) {
+    strippedPath = strippedPath.slice('\\\\?\\'.length);
+  }
+
+  return path.win32.normalize(strippedPath);
+}
+
+function normalizeProjectPathForProvider(provider: string, projectPath: string): string {
+  if (provider !== 'codex') {
+    return projectPath;
+  }
+
+  return normalizeCodexProjectPath(projectPath);
+}
+
+export const sessionsDb = {
+  createSession(
+    sessionId: string,
+    provider: string,
+    projectPath: string,
+    customName?: string,
+    createdAt?: string,
+    updatedAt?: string,
+    jsonlPath?: string | null
+  ): void {
+    const db = getConnection();
+    const createdAtValue = normalizeTimestamp(createdAt);
+    const updatedAtValue = normalizeTimestamp(updatedAt);
+    const normalizedProjectPath = normalizeProjectPathForProvider(provider, projectPath);
+
+    // First, ensure the project path is recorded in the projects table,
+    // since it's a foreign key in the sessions table.
+    projectsDb.createProjectPath(normalizedProjectPath);
+
+    db.prepare(
+      `INSERT INTO sessions (session_id, provider, custom_name, project_path, jsonl_path, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, COALESCE(?, CURRENT_TIMESTAMP), COALESCE(?, CURRENT_TIMESTAMP))
+       ON CONFLICT(session_id, provider) DO UPDATE SET
+         updated_at = excluded.updated_at,
+         project_path = excluded.project_path,
+         jsonl_path = excluded.jsonl_path,
+         custom_name = COALESCE(excluded.custom_name, sessions.custom_name)`
+    ).run(
+      sessionId,
+      provider,
+      customName ?? null,
+      normalizedProjectPath,
+      jsonlPath ?? null,
+      createdAtValue,
+      updatedAtValue
+    );
+  },
+
+  updateSessionCustomName(sessionId: string, customName: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET custom_name = ?
+       WHERE session_id = ?`
+    ).run(customName, sessionId);
+  },
+
+  createSessionName(sessionId: string, provider: string, customName: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET custom_name = ?
+       WHERE session_id = ? AND provider = ?`
+    ).run(customName, sessionId, provider);
+  },
+
+  getSessionById(sessionId: string): SessionMetadataLookupRow | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, created_at, updated_at
+         FROM sessions
+         WHERE session_id = ?
+         ORDER BY updated_at DESC
+         LIMIT 1`
+      )
+      .get(sessionId) as SessionMetadataLookupRow | undefined;
+
+    return row ?? null;
+  },
+
+  getAllSessions(): SessionRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, created_at, updated_at
+         FROM sessions`
+      )
+      .all() as SessionRow[];
+  },
+
+  getSessionsByProjectPath(projectPath: string): SessionRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, created_at, updated_at
+         FROM sessions
+         WHERE project_path = ?`
+      )
+      .all(projectPath) as SessionRow[];
+  },
+
+  getSessionName(sessionId: string, provider: string): string | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT custom_name
+         FROM sessions
+         WHERE session_id = ? AND provider = ?`
+      )
+      .get(sessionId, provider) as { custom_name: string | null } | undefined;
+
+    return row?.custom_name ?? null;
+  },
+
+  getSessionNames(sessionIds: string[], provider: string): Map<string, string> {
+    if (sessionIds.length === 0) return new Map();
+
+    const db = getConnection();
+    const placeholders = sessionIds.map(() => '?').join(',');
+    const rows = db
+      .prepare(
+        `SELECT session_id, custom_name
+         FROM sessions
+         WHERE session_id IN (${placeholders})
+           AND provider = ?
+           AND custom_name IS NOT NULL`
+      )
+      .all(...sessionIds, provider) as SessionNameLookupRow[];
+
+    return new Map(rows.map((row) => [row.session_id, row.custom_name]));
+  },
+
+  deleteSession(sessionId: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM sessions WHERE session_id = ?').run(sessionId);
+  },
+};
--- a/server/modules/database/repositories/users.ts
+++ b/server/modules/database/repositories/users.ts
@@ -0,0 +1,140 @@
+/**
+ * User repository.
+ *
+ * Provides typed CRUD operations for the `users` table.
+ * This is a single-user system, but the schema supports multiple
+ * users for forward compatibility.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type UserRow = {
+  id: number;
+  username: string;
+  password_hash: string;
+  created_at: string;
+  last_login: string | null;
+  is_active: number;
+  git_name: string | null;
+  git_email: string | null;
+  has_completed_onboarding: number;
+};
+
+type UserPublicRow = Pick<UserRow, 'id' | 'username' | 'created_at' | 'last_login'>;
+
+type UserGitConfig = {
+  git_name: string | null;
+  git_email: string | null;
+};
+
+type CreateUserResult = {
+  id: number | bigint;
+  username: string;
+};
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const userDb = {
+  /** Returns true if at least one user exists in the database. */
+  hasUsers(): boolean {
+    const db = getConnection();
+    const row = db.prepare('SELECT COUNT(*) as count FROM users').get() as {
+      count: number;
+    };
+    return row.count > 0;
+  },
+
+  /** Inserts a new user and returns the created ID + username. */
+  createUser(username: string, passwordHash: string): CreateUserResult {
+    const db = getConnection();
+    const result = db
+      .prepare('INSERT INTO users (username, password_hash) VALUES (?, ?)')
+      .run(username, passwordHash);
+    return { id: result.lastInsertRowid, username };
+  },
+
+  /**
+   * Looks up an active user by username.
+   * Returns the full row (including password hash) for auth verification.
+   */
+  getUserByUsername(username: string): UserRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare('SELECT * FROM users WHERE username = ? AND is_active = 1')
+      .get(username) as UserRow | undefined;
+  },
+
+  /** Updates the last_login timestamp. Non-fatal — logs but does not throw. */
+  updateLastLogin(userId: number): void {
+    try {
+      const db = getConnection();
+      db.prepare(
+        'UPDATE users SET last_login = CURRENT_TIMESTAMP WHERE id = ?'
+      ).run(userId);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error('Failed to update last login', { error: message });
+    }
+  },
+
+  /** Returns public user fields by ID (no password hash). */
+  getUserById(userId: number): UserPublicRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, username, created_at, last_login FROM users WHERE id = ? AND is_active = 1'
+      )
+      .get(userId) as UserPublicRow | undefined;
+  },
+
+  /** Returns the first active user. Used for single-user mode lookups. */
+  getFirstUser(): UserPublicRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, username, created_at, last_login FROM users WHERE is_active = 1 LIMIT 1'
+      )
+      .get() as UserPublicRow | undefined;
+  },
+
+  /** Stores the user's preferred git name and email. */
+  updateGitConfig(
+    userId: number,
+    gitName: string,
+    gitEmail: string
+  ): void {
+    const db = getConnection();
+    db.prepare('UPDATE users SET git_name = ?, git_email = ? WHERE id = ?').run(
+      gitName,
+      gitEmail,
+      userId
+    );
+  },
+
+  /** Retrieves the user's git identity (name + email). */
+  getGitConfig(userId: number): UserGitConfig | undefined {
+    const db = getConnection();
+    return db
+      .prepare('SELECT git_name, git_email FROM users WHERE id = ?')
+      .get(userId) as UserGitConfig | undefined;
+  },
+
+  /** Marks onboarding as complete for the given user. */
+  completeOnboarding(userId: number): void {
+    const db = getConnection();
+    db.prepare(
+      'UPDATE users SET has_completed_onboarding = 1 WHERE id = ?'
+    ).run(userId);
+  },
+
+  /** Returns true if the user has finished the onboarding flow. */
+  hasCompletedOnboarding(userId: number): boolean {
+    const db = getConnection();
+    const row = db
+      .prepare('SELECT has_completed_onboarding FROM users WHERE id = ?')
+      .get(userId) as { has_completed_onboarding: number } | undefined;
+    return row?.has_completed_onboarding === 1;
+  },
+};
--- a/server/modules/database/repositories/vapid-keys.ts
+++ b/server/modules/database/repositories/vapid-keys.ts
@@ -0,0 +1,57 @@
+/**
+ * VAPID keys repository.
+ *
+ * Stores and retrieves the Web Push VAPID key pair.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type VapidKeyRow = {
+  public_key: string;
+  private_key: string;
+};
+
+type VapidKeyPair = {
+  publicKey: string;
+  privateKey: string;
+};
+
+export const vapidKeysDb = {
+  /** Returns the latest stored VAPID key pair, or null when unset. */
+  getVapidKeys(): VapidKeyPair | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT public_key, private_key FROM vapid_keys ORDER BY id DESC LIMIT 1'
+      )
+      .get() as Pick<VapidKeyRow, 'public_key' | 'private_key'> | undefined;
+
+    if (!row) return null;
+    return {
+      publicKey: row.public_key,
+      privateKey: row.private_key,
+    };
+  },
+
+  /** Persists a new VAPID key pair. */
+  createVapidKeys(publicKey: string, privateKey: string): void {
+    const db = getConnection();
+    db.prepare(
+      'INSERT INTO vapid_keys (public_key, private_key) VALUES (?, ?)'
+    ).run(publicKey, privateKey);
+  },
+
+  /** Replaces all existing keys with a fresh pair. */
+  updateVapidKeys(publicKey: string, privateKey: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM vapid_keys').run();
+    vapidKeysDb.createVapidKeys(publicKey, privateKey);
+  },
+
+  /** Deletes all VAPID key rows. */
+  deleteVapidKeys(): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM vapid_keys').run();
+  },
+};
+